ENRU

Введение

Добро пожаловать в документацию Genome!

Здесь вы найдете полезную информацию и обучающие материалы, которые помогут вам понять, как использовать страницы оплаты Genome, Host to Host интеграцию и запрос API по требованию.

Для того чтобы начать работу с Genome, вам нужно зарегистрировать мультивалютный бизнес-аккаунт по ссылке merchant.genome.eu.

Платежная страница

Краткий обзор

Теперь вы можете легко принимать платежи, настраивать подписку и увеличивать конверсию платежей всего за несколько кликов. Это руководство охватывает основы создания учетной записи, настройки платежной страницы, создания продуктов и описание возможностей вашего аккаунта.

Общая информация

Чтобы начать примать платежи, используя страницу оплаты Genome, Вам необходимо:

Создание продукта

Вы можете продавать товары, используя инструменты Genome (создание продуктов в мерчант портале mPortal) или передавать нам кастомные продукты, используя для этого custom product API.

Платежные методы

Здесь Вы можете управлять платежными методами, доступными для вашего бизнес-аккаунта. Для этого необходимо просто активировать/деактивировать нужные платежные методы, указать валюту и для каких стран они буду доступны.

Для сквозного выбора платежного метода используйте параметр "payment_method". Для этого необходимо скопировать название платежного метода и передать его значение в параметре - "payment_method". Значения параметра доступны в разделе Payment pages, вкладка Payment methods.

Параметры платежного метода:

Тип интеграции Описание
redirect <input type='hidden' name='payment_method' value='Credit card'>
popup / iframe data-payment_method="Credit card"

Кастомайзер платежной формы

Genome-кастомайзер платежной формы позволяет вам:

Пример iFrame интеграции

iFrame пример:

<div>
    <script src="https://hpp-service.genome.eu/paymentPage.js"
        class="pspScript"
        data-iframesrc="https://hpp-service.genome.eu/hpp"
        data-buttontext="Pay!"
        data-name="Application"
        data-key="pkTest_67pcq3B5i8N7utM7WRNM6ZGvxFm"
        data-signature="199d5022dd7be0a8313954bcc7d4fe0ec9b005beab2ef7e00932cc48e2381f87"
        data-type="integrated"
        data-width="auto"
        data-height="auto"
        data-email="john.doe@test.com"
        data-phone="1234567890"
        data-address="5th avn."
        data-city="New York"
        data-country="USA"
        data-zip="12100"
        data-success_url="https://www.merchant.com/success"
        data-decline_url="https://www.merchant.com/decline">
    </script>
    <form class='pspPaymentForm'></form>
    <iframe id='psp-hpp-199d5022dd7be0a8313954bcc7d4fe0ec9b005beab2ef7e00932cc48e2381f87'></iframe>
</div>


Параметры запроса:

Параметры Описание
data-buttontext Текст кнопки оплаты
data-name Имя приложения
data-key Уникальный ключ, сгенерированный Genome
data-signature Уникальная подпись приложения, сгенерированная Genome, либо мерчантом
data-type Значение типа по умолчанию - integrated
data-width Ширина iFrame
data-height Высота iFrame

Дополнительные поля для iFrame формы:

Параметры Описание
uniqueTransactionId Парамет позволяет передать уникальный Id транзакции, и после получить значение в callback. Если мерчант не передает значение, Genome сгенерирует Id самостоятельно.
productPublicId Параметр позволяет предопределить продукт для платежной странице, в поле значение необходимо передать Id продукта (из мерчант портала)
email Email клиента
firstname Имя клента
lastname Фамилия клиента
phone Телефоный номер
address Адрес
city Город
country Страна
zip Почтовый индекс
success_url Редирект при успешной оплате
decline_url Редирект при отклоненой оплате
payment_method Платежный метод
locale Язык платежной страницы

Примечание: поле data-phone, является необязательным, или же по требованию банка экваера. Управления полями на платежной странице находится в мерчант портале, вкладка Payment pages, раздел Payment form.

Пример Pop Up интеграции

Pop Up пример:


<div>
    <form class='pspPaymentForm'>
        <script src="https://hpp-service.genome.eu/paymentPage.js"
            class="pspScript"
            data-iframesrc="https://hpp-service.genome.eu/hpp"
            data-buttontext="Pay!"
            data-name="Application"
            data-key="pkTest_67pcq3B5i8N7utM7WRNM6ZGvxFm"
            data-signature="199d5022dd7be0a8313954bcc7d4fe0ec9b005beab2ef7e00932cc48e2381f87"
            data-displaybuybutton="true"
            data-type="popup"
            data-email="john.doe@test.com"
            data-phone="1234567890"
            data-address="5th avn."
            data-city="New York"
            data-country="USA"
            data-zip="12100"
            data-success_url="https://www.merchant.com/success"
            data-decline_url="https://www.merchant.com/decline">
        </script>
    </form>
</div>

Параметры запроса:

Параметры Описание
data-buttontext Текст кнопки оплаты
data-name Имя приложения
data-key Уникальный ключ, сгенерированный Genome
data-signature Уникальная подпись приложения, сгенерированная Genome, либо мерчантом
data-displaybuybutton Трансляция кнопки
data-type Значение типа - popup

Дополнительные поля для Pop up формы:

Параметры Описание
uniqueTransactionId Парамет позволяет передать уникальный Id транзакции, и после получить значение в callback. Если мерчант не передает значение, Genome сгенерирует Id самостоятельно.
productPublicId Параметр позволяет предопределить продукт для платежной странице, в поле значение необходимо передать Id продукта (из мерчант портала)
email Email клиента
firstname Имя клента
lastname Фамилия клиента
phone Телефоный номер
address Адрес
city Город
country Страна
zip Почтовый индекс
success_url Редирект при успешной оплате
decline_url Редирект при отклоненой оплате
payment_method Платежный метод
locale Язык платежной страницы

Примечание: поле data-phone, является необязательным, или же по требованию банка экваера. Управления полями на платежной странице находится в мерчант портале, вкладка Payment pages, раздел Payment form.

Пример Redirect интеграции

Redirect пример:


<form action='https://hpp-service.genome.eu/hpp' class='redirect_form' method='post'>
    <input type='hidden' name='key' value='pkTest_23pcq3B5i8N7utM7WRNM6ZGvxFmHE4W0'>
    <input type='hidden' name='signature' value='199d5077dd7be9a8313954bcc7d4fe7ec9b005beab2ef7e00932cc48e3981f23'>
    <input type="hidden" name='uniqueUserId' value='user1'>
    <button type='submit'>Pay</button>
</form>

Parameters of Redirect form

Параметры Описание
key Уникальный ключ, сгенерированный Genome
signature Уникальная подпись приложения, сгенерированная Genome, либо мерчантом
uniqueuserid Уникальный Id клиента в системе мерчанта

Дополнительные поля для редирект формы:

Параметры Описание
uniqueTransactionId Парамет позволяет передать уникальный Id транзакции, и после получить значение в callback. Если мерчант не передает значение, Genome сгенерирует Id самостоятельно.
productPublicId Параметр позволяет предопределить продукт для платежной странице, в поле значение необходимо передать Id продукта (из мерчант портала)
email Email клиента
firstname Имя клента
lastname Фамилия клиента
phone Телефоный номер
address Адрес
city Город
country Страна
zip Почтовый индекс
success_url Редирект при успешной оплате
decline_url Редирект при отклоненой оплате
payment_method Платежный метод
locale Язык платежной страницы

Локаль на платежной странице

Genome предоставляет различные языки для платежной страницы.

Список доступных языков ниже:

Язык Значение
Английский (US) "en-US"
Русский "ru-RU" или "ru"
Немецкий "de-DE"
Французский "fr-FR"
Португальский "pt-PT"
Итальянский "it-IT"
Испанский "es-ES"
Турецкий "tr-TR"
Шведский "sv-SE"
Норвежский "no-NO"
Датский "da-DA"
Финский "fl-FL"

По умолчанию отображается английский язык.

Давайте рассмотрим пример с испанской локалью:

Тип платежной формы Пример кода
redirect <input type='hidden' name='locale' value='es-ES'>
popup / iframe data-locale="es-ES"

Custom product API

Пример Custom product API

<div>
    <form class='pspPaymentForm'>
        <script
            src="https://hpp-service.genome.eu/paymentPage.js"
            class="pspScript"
            data-iframesrc="https://hpp-service.genome.eu/hpp"
            data-key="pkTest_56137fd80ffc4a639cf91e81941d1f51"
            data-signature="bac1c2876f98149d225da91c85956ece1d695809d2a32fff81459c04ff77580b"
            data-uniqueuserid="testUserId"
            data-cardholdername="John Doe"
            data-address="New road st 1"
            data-city="Boston"
            data-country="USA"
            data-phone="+1231234123"
            data-email="johnappleseed@gmail.com"
            data-customproduct='[{"productId":12345,"productType":"subscriptionProduct","productName":"Demo custom product","currency":"USD","amount":100,"productDescription":"Monthly subscription for","subscriptionLength":"2","subscriptionPeriod":"24H","subscriptionEndDate":"1735689600"}]'
            data-type="popup">
        </script>
    </form>
</div>

В случае, если Вы хотите, чтобы выбор товара происходил на вашей стороне, у вас есть возможность пропустить создание продуктов в Мерчант портале Genome. Для использования своих продкутов, просто отправьте запрос “POST” с параметром “customproduct”. Этот параметр должен содержать нужный Вам набор товаров. Метод запроса: POST



Параметры пользовательского запроса:

Параметры Обязательный Тип Описание
productId Да string ID продукта.
productName Да string Имя продукта, будет показано на плетежной странице.
productType Да string Тип продукта. Значения:
  • fixedProduct - продукт с фиксированной стоимостью;
  • subscriptionProduct - продукт с подпиской;
  • trialProduct - пробный продукт.
productDescription Нет string Описание продукта, будет показано на плетежной странице.
currency Да string Валюта, которая будет взыматься за продукт.
amount Да float Цена за продукт.
discount Нет float Сумма дисконта по продукту.
discountType Нет string Тип дисконта в процентном или денежном эквиваленте. возможен только для ‘fixed’ и ‘subscription’ типов продуктов. Значения:
  • amountOff
  • percentOff
subscriptionLength Нет int Периодичность продукта подписки.
subscriptionPeriod Нет string Периоды срабатывания платежа подписки продукта:
  • 24H - через 24 часа;
  • 7D - через 7 дней;
  • 30D - через 30 дней;
  • 365D - через 365 дней.
subscriptionBillingCycles Нет int Количество биллинг циклов.
postTrialProductId Нет string ID пост-триал продукта, обязательное для trialProduct типа.
trialLength Нет int Длина триал продукта, обязательное для trialProduct типа.
trialPeriod Нет string Период триала, обязательное для trialProduct типа. Возможные значения:
  • 24H;
  • 7D;
  • 30D;
  • 365D.
subscriptionTrialEnd Нет float Конечная дата пробного продукта.
subscriptionTrialPrice Нет float Цена пробного продукта. Сумма будет в обработке с ‘trialStart’ до ‘trialEnd’ периода.
subscriptionTrialStart Нет float Начальная дата обработки платежа пробного продукта.
subscriptionTrialEnd Нет float Конец даты подписки триального продукта.

Авторизационное API

Тип формы Пример кода
Redirect <input type="hidden" name="transactionFlow" value='{"transactionType":"AUTH", "transactionLength":1, "transactionPeriod":"Day","postTransactionType":"SETTLE"}'>
Pop Up/iFrame data-transactionflow='{"transactionType":"AUTH", "transactionLength":1, "transactionPeriod":"Day","postTransactionType":"SETTLE"}'


ПАРАМЕТР ОБЯЗАТЕЛЬНОЕ ТИП ОПИСАНИЕ
transactionType да string Тип транзакции. Необходимо передавать "AUTH" в значение.
transactionLength да int Длина между "AUTH" и следующим типом транзакции ("SETTLE" или "VOID"). Длина зависит от настроек банка эквайера.
transactionPeriod да string Транзакционный период. TНеобходимо передавать "day" в значении.
postTransactionType да string Следующий тип транзакций после "AUTH". Значения могут быть "VOID" или "SETTLE". "VOID" является отменой авторизации. "SETTLE" является списанием средств

Примечание: Вы должны предоставить информацию о продукте на случай использования API авторизации. Вы можете использовать параметры «productPublicId» или «customproduct».

Callback значение

Пример callback ответа:

{
    "transactionId":"hpp1465480732.893mId1274aId0",
    "reference":"SLFF00000000779A7BR1",
    "uniqueUserId":"testUserId",
    "totalAmount":100,
    "currency":"USD",
    "transactionType":"SALE",
    "status":"success",
    "message":"Transaction processed successfully",
    "code":0,
    "productList":
        [
            {
                "productId":"12345",
                "name":"Demo custom product",
                "amount":100,
                "currency":"USD"
            }
        ],
    "checkSum":"78705e06b853d0035a03019e1861c6a96d049798820dfd400e5bf874696d6dea"
}

Callback - это ответ о состоянии транзакции. Приходит в формате POST, для наглядности, в документации показан в формате JSON. Описание callback полей ниже:

Параметр Описание
transactionId Уникальный ID транзакции
reference Уникальный reference в системе Genome
uniqueUserId Уникальный ID пользователя.
totalAmount Сумма транзакции.
currency Валюта транзакции.
transactionType Тип транзакции.
status Статус транзакции.
code Код ответа по транзакции. Детальное описание кодов в разделе “Коды ответов”.
message Сообщение о статусе транзакции. Детальное описание кодов в разделе “Коды ответов”.
productList Список продуктов, которые процессились. Каждый продукт содержит поля:
  • productId
  • name
  • amount
  • currency
checkSum Check sum позволяет провести сверку между тем, что отправили и какой результат в callback получили.

В случае, если мерчант, при получении коллбэка, отвечает кодом - 200 и в теле содержится текст - ОК, то такой коллбэк считается успешно принятым. В любых других случаях - коллбэк считается непринятым, будут продолжаться попытки отправки коллбэка мерчанту.

Примеры ответов на коллбэк ниже:

Код Тело Описание
200 OK Коллбэк успешно доставлен мерчанту, текст ОК всегда является обязательным
500 ОК Коллбэк не принят мерчантом, неверный код ответа

Примечание: все поля, которые приходят в коллбэк ответе, участвуют в подсчете значения checkSum, детальное описание ниже.

API повторного выставления счета

Пример заппроса:

<?php
    array (
      'publicKey' => 'pkTest_56137fd80ffc4a639cf91e81941d1f51',
      'signature' => 'bac1c2876f98149d225da91c85956ece1d695809d2a32fff81459c04ff77580b',
      'rebillToken' => '575955d2-5818-4806-8498-7855f3666259',
      'productId' => 'myproductId',
      'uniqueUserId' => 'subscriptionfull',
      'amount' => 100,
      'productName' => 'Monthlysubscription',
      'currency' => 'USD',
      'productType' => 'subscriptionProduct',
      'subscriptionLength' => 1,
      'subscriptionPeriod' => '24H',
      'subscriptionTrialPrice' => 99.9,
      'subscriptionTrialStart' => 1447337995,
      'subscriptionTrialEnd' => 1497339252,
      'subscriptionEndDate' => 1498030452,
      'cardHolderName' => 'Mike Smith',
      'firstName' => 'Mike',
      'lastName' => 'Smith',
      'email' => 'mike@test.com',
      'country' => 'FRA',
      'city' => 'Paris',
      'address' => 'street 21',
      'zip' => '7121',
      'phone' => '4422211190'
    )
?>

API повторного выставления счета (Rebilling API) -  это уникальный способ взимать плату с ваших клиентов, основанный на вашем собственном графике с использованием токенов кредитных карт. Эта функция может быть активирована в настройках виджета вашего приложения. Пожалуйста, обратите внимание: если функция активирована, то в вашей форме оплаты появится дополнительный флажок. Если клиент делает отметку флажком, вам отправляется токен через callback ответ после того как клиент совершает платеж. Вы можете использовать параметры, представленные ниже, чтобы повторно выставлять счета вашему клиенту после получения платежного токена.

URL запроса: https://hpp-service.genome.eu/api/rebilling
Метод запроса: POST.

Описание параметров

Параметры Обязательный Описание
publicKey Да Публичный ключ приложения. Вы можете найти его в разделе Payment pages, вкладка General
uniqueUserId Да Уникальный ID пользователя в вашей системе.
rebillToken Да Уникальное значение token параметра.
productId Да Уникальный ID продукта. Вы можете найти его в разделе Payment pages, вкладка “Products to sell”.
productName Да Имя продукта.
productDescription Опциональный Описание продукта.
productType Да Тип продукта. Значения:
  • fixedProduct - продукт с фиксированной стоимостью;
  • subscriptionProduct - продукт с подпиской;
  • trialProduct - пробный продукт.
currency Опциональный Валюта, которая будет взыматься за продукт.
amount Да Цена за продукт.
discount Опциональный Сумма дисконта по продукту.
discountType да, если установлен ‘discount’ Тип дисконта в процентном или денежном эквиваленте. возможен только для ‘fixed’ и ‘subscription’ типов продуктов. Значения:
  • amountOff
  • percentOff
subscriptionLength Опциональный Периодичность продукта подписки.
subscriptionPeriod Опциональный Периоды срабатывания платежа подписки продукта:
  • 24H - через 24 часа;
  • 7D - через 7 дней;
  • 30D - через 30 дней;
  • 365D - через 365 дней.
subscriptionEndDate Опциональный Дата завершения подписки
subscriptionTrialPrice Опциональный Цена пробного продукта.
subscriptionTrialStart Опциональный Начальная дата обработки платежа пробного продукта.
subscriptionTrialEnd Опциональный Конечная дата обработки платежа пробного продукта.
trialLength Опциональный Периодичность пробного продукта.
trialPeriod Опциональный Периоды срабатывания платежа пробного продукта:
  • 24H - через 24 часа;
  • 7D - через 7 дней;
  • 30D - через 30 дней;
  • 365D - через 365 дней.
postTrialProductId Опциональный Доступен при условии, что ‘trialProduct’ это - string. Данный тип продукта будет в обработке после пробного продукта. Важно: Если Вы хотите использовать пост триальный продукт, то его нужно создать в Genome мерчант портале.
signature Да Genome подпись. Описание по генерации подписи ниже.
cardHolderName Опциональный Имя держателя карты (если не передается значение для этого поля - значение будет браться с начальной транзакции).
firstName Опциональный Имя (если не передается значение для этого поля - значение будет браться с начальной транзакции).
lastName Опциональный Фамилия (если не передается значение для этого поля - значение будет браться с начальной транзакции).
email Опциональный Email (если не передается значение для этого поля - значение будет браться с начальной транзакции)
country Опциональный Страна (если не передается значение для этого поля - значение будет браться с начальной транзакции).
city Опциональный Город (если не передается значение для этого поля - значение будет браться с начальной транзакции).
address Опциональный Адрес (если не передается значение для этого поля - значение будет браться с начальной транзакции).
zip Опциональный Почтовый индекс (если не передается значение для этого поля - значение будет браться с начальной транзакции).
phone Опциональный Номер телефона (если не передается значение для этого поля - значение будет браться с начальной транзакции).

Пример callback ответа:

{
  "requestSuccess": true,
  "payload": {
    "transactionId": "hppR1495179676.5908mId3126aId1335",
    "reference":"SLFF00000000779A7BR1",
    "uniqueUserId": "my_test_id21",
    "totalAmount": 100,
    "currency": "USD",
    "transactionType": "SALE",
    "status": "success",
    "message": "Transaction processed successfully",
    "code": 0,
    "productList": [
      {
        "productId": "12345",
        "name": "Test product name",
        "amount": 100,
        "currency": "USD"
      }
    ],
    "checkSum": "0834aeaaf25ab42168b451eabd9f4c2c450d39d3db57d8a6c939a15000da3e91"
  }
}

Callback значение

Callback - это ответ о состоянии транзакции. Приходит в формате POST, для наглядности, в документации показан в формате JSON. Описание callback полей ниже:

Параметр Описание
transactionId Уникальный ID транзакции
reference Уникальный reference в системе Genome
uniqueUserId Уникальный ID пользователя.
totalAmount Сумма транзакции.
currency Валюта транзакции.
transactionType Тип транзакции.
status Статус транзакции.
code Код ответа по транзакции. Детальное описание кодов в разделе “Коды ответов”.
message Сообщение о статусе транзакции. Детальное описание кодов в разделе “Коды ответов”.
productList Список продуктов ввиде массива. Каждый продукт содержит поля:
  • productId
  • name
  • amount
  • currency
checkSum Check sum позволяет провести сверку между тем, что отправили и какой результат в callback получили.

В случае, если мерчант, при получении коллбэка, отвечает кодом - 200 и в теле содержится текст - ОК, то такой коллбэк считается успешно принятым. В любых других случаях - коллбэк считается непринятым, будут продолжаться попытки отправки коллбэка мерчанту.

Примеры ответов на коллбэк ниже:

Код Тело Описание
200 OK Коллбэк успешно доставлен мерчанту, текст ОК всегда является обязательным
500 ОК Коллбэк не принят мерчантом, неверный код ответа

Примечание: все поля, которые приходят в коллбэк ответе, участвуют в подсчете значения checkSum, детальное описание ниже.

API отмены подписки

Пример запроса:

<?php

array (
  'publicKey' => 'pkLive_5617970296ec43c48a2b5446d',
  'transactionId': 'hpp1467893228.4626mId571aId0',
  'uniqueUserId' => 'subscriptionfull',
  'signature' => '039539689c72f018ab7beee0389f935f',
)

?>

API по отмене подписки (Cancel subscription API) - это способ позволяющий отписать ваших клиентов от Rebilling API. Эта функция может быть отключена в настройках виджета вашего приложения. Кроме того, вы можете использовать параметры, представленные ниже, чтобы отменить подписку.

Метод запроса: POST.
URL запроса: https://hpp-service.genome.eu/api/cancel

Параметры запроса

Параметры Обязательный Описание
publicKey Да Публичный ключ приложения. Вы можете найти его в разделе Payment pages, вкладка General
transactionId Да Уникальный ID транзакции.
uniqueUserId Да Уникальный ID пользователя в вашей системе.
signature Да Genome подпись. Описание по генерации подписи ниже.

Пример callback значения:

{
    "requestSuccess": true,
    "payload": {
        "transactionId": "hpp1467893228.4626mId571aId0",
        "message": "Subscription products successfully stopped.",
        "status": "Success",
        "productList": [{
            "productId": "p_a98f28b23a",
            "name": "subscription",
            "amount": 2,
            "currency": "EUR"
        }],
    "checkSum": "810ed9abe39347211665d403fdea62919aa4d5fe4cb0077bbb8b47db160248da"
    }
}

Callback значение

Описание callback полей ниже:

Параметр Описание
transactionId Уникальный ID транзакции
message Сообщение о статусе транзакции. Детальное описание кодов в разделе “Коды ответов”.
status Статус транзакции.
productList Список продуктов ввиде массива. Каждый продукт содержит поля:
  • productId
  • name
  • amount
  • currency
checkSum Check sum позволяет провести сверку между тем, что отправили и какой результат в callback получили.

В случае, если мерчант, при получении коллбэка, отвечает кодом - 200 и в теле содержится текст - ОК, то такой коллбэк считается успешно принятым. В любых других случаях - коллбэк считается непринятым, будут продолжаться попытки отправки коллбэка мерчанту.

Примеры ответов на коллбэк ниже:

Код Тело Описание
200 OK Коллбэк успешно доставлен мерчанту, текст ОК всегда является обязательным
500 ОК Коллбэк не принят мерчантом, неверный код ответа

Примечание: все поля, которые приходят в коллбэк ответе, участвуют в подсчете значения checkSum, детальное описание ниже.

API для отмены пост-триального продукта

API для отмены пост-триального продукта это - способ провести отмену посттриального продукта через API запрос.

Пример запроса:

<?php

array (
  'publicKey' => 'pkLive_4417970296ec43c48a2b5776d',
  'transactionId'=> 'hpp1501640316.4483mId3125aId1281',
  'signature' => '799539689c72f018ab7beee0389f9440'
)

?>

URL запроса: https://hpp-service.genome.eu/api/cancel_post_trial
Метод запроса: POST.

Параметры запроса:

Параметр Обязательный Описание
publicKey Да Публичный ключ приложения. Вы можете найти его в разделе Payment pages, вкладка General
transactionId Да ID транзакции.
signature Да Genome подпись. Описание по генерации подписи ниже.

Пример коллбэка:

{
    "requestSuccess": true,
    "payload": {
        "transactionId": "hpp1501652396.4483mId3125aId1281",
        "message": "Post trial canceled for user `auto_2E6LwT8NIQbK1yZZ`",
        "status": "Success",
        "checkSum": "f40e8d4896b2cdb3d9097ad6476f851b2ab5ba18db2f19b6d28c355ca7734f80"
    }
}

Описание коллбэк параметров:

Параметр Описание
transactionId ID транзакции.
message Сообщение о статусе транзакции. Детальное описание кодов в разделе “Коды ответов”.
status Статус транзакции.
checkSum Check sum позволяет провести сверку между тем, что отправили и какой результат в callback получили.

Example callback on repeated request:

{
    "requestSuccess": false,
    "description": "Post-trial 235 is already cancelled"
}

API по выдаче возврата

Пример запроса по выдаче возврата:

<?php

array (
  'publicKey' => 'pkLive_2337970296ec43c48a2b5336s',
  'transactionId'=> 'hpp1467893228.4626mId571a0',
  'signature' => '021539489c2f8ab7baee0389f735f'
)

?>

API по выдаче возврата позволяет делать возврат средств на стороне мерчанта. Используйте описание ниже для осуществления возврата клиенту.

Метод запроса: POST.
Request URL: https://hpp-service.genome.eu/api/refund

Параметры запроса

Параметр Обязательный DESCRIPTION
publicKey да Публичный ключ в системе Genome.
transactionId да Уникальный ID транзакции.
signature да Подпись в системе Genome.

Example callback:

{
    "requestSuccess":true,
    "payload":{
        "message":"Refund processed successfully",
        "status":"Success",
        "transactionId":"hppAR149509622.3937mId3126a1446",
        "checkSum":"5573d19969c61517c155879c8cf5ce292ce39d94ba94364d8c658e4a7f78"
        }
    }

Параметры callback ответа

Описание callback полей

PARAMETER DESCRIPTION
requestSuccess True - запрос прошел успешно. False - ошибка в запросе.
payload Массив с данными о транзакции.
message Сообщение о статусе транзакции.
status Статус транзакции.
transactionId Уникальный ID транзакции.
checkSum Check sum значение.

Расширенный возврат

АПИ по расширенному возврату позволяет проводить частичный или полный возврат транзакции.

Пример запроса


    array
       (
          'publicKey' => 'pkTest_5617970296ec43c48a2b5446d',
          'transactionId'=> 'hpp1467893228.4626mId571aId0',
          'signature' => '039539489c72f018ab7baee0389f735f',
          'amount' => 9.99,
          'currency' => 'USD'
       );

URL для запроса: https://hpp-service.genome.eu/api/extended_refund Метод запроса: POST.

Параметры запроса:

ПАРАМЕТР ОБЯЗАТЕЛЬНЫЙ ОПИСАНИЕ
publicKey Да Публичный ключ платежной страницы
transactionId Да Уникальный идентификатор транзакции
signature Да Подпись платежной страницы. Значение может быть взято из секции Палтежный формы.
amount Да Сумма возврата
currency Да Валюта возврата

Пример ответа


    {
        "transactionId":"hppAR1495096440.3937mId3126aId1335",
        "reference": "RFF0000000039FDAEGG",
        "timestamp": 1614001691,
        "status": "success",
        "code": 0,
        "message": "Transaction processed successfully"
        "checkSum":"8237d19969c61517c155879c8cf5ce292ce39d948c6bba94364d8c658e4a7f26"
    }

Параметры ответа:

ПАРАМЕТР ОПИСАНИЕ
transactionId Уникальный идентификатор транзакции
reference Референс транзакции
timestamp Время транзакции в UNIX формате
status Статус транзакции
code Код ответа
message Сообщение
checkSum Подпись для параметров ответа

Вычисление подписи для платежной страницы

Если вы хотите посчитать значение подписи (signature) вашей платежной формы самостоятельно, используйте описание алгоритма ниже:


<!--Для примера используем форму -->

<form method="post" action="https://hpp-service.genome.eu/hpp">
    <input type="hidden" name="key" value="Публичный_ключ_из_мпортала">
    <input type="hidden" name="customproduct" value="[{'productId':'1','productType':'fixedProduct','productName':'Product name','currency':'RUB','amount':100}]">
    <input type="hidden" name="signature" value="Сюда_надо_подставить_полученную_сигнатуру">
    <button type='submit'>Pay</button>
</form>

Рассмотрим реальный пример подписи на основании формы приведенной выше:


Вычисление значения checkSum для коллбэка

Если вы хотите посчитать и сверить значение checkSum коллбэка, используйте описание алгоритма ниже:

Примечание: все поля, которые приходят в коллбэк ответе, участвуют в подсчете значения checkSum.


<?php
$callbackData = array (
    'transactionId' => 'hpp1462257324.5236mId548aId9',
    'reference' => 'SLFF00000000779A7BR1',
    'uniqueUserId' => 'my_User_Id22',
    'totalAmount' => 101,
    'currency' => 'USD',
    'transactionType' => 'SALE',
    'status' => 'success',
    'message' => 'Transaction processed successfully',
    'code' => 0,
    'productList' =>
        array (
            0 =>
                array (
                    'productId' => 'myProducId2',
                    'name' => 'goods 2',
                    'amount' => 100,
                    'currency' => 'USD',
                ),
            1 =>
                array (
                    'productId' => 'myProducId1',
                    'name' => 'goods 1',
                    'amount' => 1,
                    'currency' => 'USD',
                ),
        ),
    'billToken' => '569ded06-c1c0-4ecb-9b9c-59c1630f6969',
    'customParameters' =>
        array (
            'custom_param1' => 'param value 3',
            'custom_param2' => 'param value 2',
        ),
    'checkSum' => '166ad6f43ab2bcedda422433cb5bf34efd75715185f226bc9720de53ee70a079',
);
?>

Для вложенных массивов используется следующий алгоритм формирования имени ключа в строке:

Для примера рассмотрим формирование ключа для подмассива productList, преобразованный в строку, он будет иметь следующий вид:

Если полностью перевести колбек представленный в примере в строку получим:


PaymentPage.js

Функции, представленные ниже, помогут вам манипулировать javascript платежной страницы и товарами, созданными на стороне Genome:

Тестовые кредитные карты

Список тестовых кредитных карт представлен ниже:

Бренд Номер карты Срок истичения CVV код
Visa 4111111111111111 10 / 2022 123
Mastercard 5191330000004415 10 / 2022 123
Visa (3Ds) 4012000300001003 10 / 2022 123
Mastercard (3Ds) 5191330000004415 10 / 2022 123
American Express 371449635398431 10 / 2022 1234
Discover 6011111111111117 10 / 2022 123
Diners Club 30569309025904 10 / 2022 123
JCB 3530111333300000 10 / 2022 123

Дополнение: * Срок истичения службы карты можно вводить любой, главное, чтоб во время тестов дата была валидной. * Для CVV кода подойдет любой 3-х значный набор цифр, только для American Express будет - 4-х значный.

Активация приложения

Для того, чтобы приступить к процессингу реальных платежей, Вам необходимо отправить созданное приложение на проверку, кликнув на кнопку “отправить на проверку” в вашем разделе “Payment pages” > ”Send for review” Наша Интеграционная Команда рассмотрит заявку и ответит Вам как можно скорее.

Сервер - Сервер интеграция

Обзор

Genome Gateway поддерживает различные типы транзакций. В текущей верии интерфейс поддерживает 9 типов операционных транзакций:

Другие определения:

Значения ECI 

MasterCard ECI значение VISA ECI значение Описание
2 5 Держатель карты успешно аутентифицирован
1 6 Аутентификация не может быть завершена, однако было предоставлено подтверждение попытки аутентификации - карта не зарегистрирована *
7 7 Аутентификации держателя карты не удалось / аутентификация не может быть завершена из-за технических или других проблем.

*Существует два варианта на данном этапе: банк Эмитента предложил Покупателю пройти авторизацию онлайн и Покупатель отказался, или банк не предлогал данную опцию.

Доступ к API Genome Gateway

Genome сервер - сервер live API и test API доступны по следующим ссылкам:

Web Сервис URL
Live Genome Gateway API Service https://gateway.genome.eu/api/cc
Test Genome Gateway API Service https://gateway-sandbox.genome.eu/api/cc
Gateway API Reference Help https://gateway.genome.eu/help/cc

Genome Gateway поддерживает различные сценарии реализации транзакций, данный документ содержит рекомендуемый, общий сценарий, описанный ниже.

  1. После выбора товаров и услуг, держатель карты нажимает «купить» или аналогичную кнопку и переходит на страницу, где он может ввести или изменить информацию о доставке и способе оплаты. Информация о Способе оплаты может включать различные варианты оплаты, например, "Оплатить с помощью кредитной карты " или другим способом. На данном этапе такая страница не должна содержать данные о номере карты, сроке действия карты, CVV2 / CVC2 или любую другую конфиденциальную информацию, связанную с картой. С целью минимизации рисков, мерчанту не следует запрашивать/хранить, информацию о кредитной карте на своей стороне.

  2. Если держатель карты выбрал опцию "Оплатить с помощью кредитной карты", то необходимо подготовить поля для запроса на авторизацию и перенаправить держателя карты к полю 'Введите информацию о кредитной карте "на странице Genome Gateway URL. Мерчант имеет возможность самостоятельно отобразить такую страницу непосредственно держателю карты. Эта страница должна содержать все поля для ввода данных карты, а также видимые / скрытые поля, относящиеся к запросу в соответствии с требованиями формата запроса авторизации. (при наличии сертификата PCI DSS).

  3. Используя AUTH/AUTH3D мерчант, отправляет запрос авторизации в Genome, далее Genome Gateway выполняет валидацию полученной в запросе информации. В случае, если запрос не проходит валидацию, то Gateway вернет ответ об ошибке.

  4. Если предоставленный номер карты принадлежит к диапазону карт с определенным методом аутентификации держателя карты (AUTH3D), Gateway вызывает соответствующий модуль аутентификации (3D Secure), который выполняет специальную обработку протокола. Если проверка подлинности держателя карты потерпела неудачу, то Genome Gateway отправит ответ об ошибке.

  5. Genome Gateway отправляет запрос на авторизацию в банк эмитента. При получении авторизации, Gateway генерирует и отправляет ответ о результате транзакции обратно в систему мерчанта. Транзакционный ответ не содержит никакой информации о кредитной карте или содержит номер карты в скрытом формате.

  6. Если авторизация прошла успешно, то ответе будет поле с референсом, который будет использоваться системой Мерчанта в будущем, для завершения или отмены полученной транзакции авторизации без использования информации о кредитной карте.

  7. После получения ответа о транзакции, Мерчант может осущетсвлять доставку заказанных товаров и / или услуг для держателя карты. В этот момент запрашиваемая сумма блокируется на карточном счете держателя карты.

  8. В случае, если мерчант хочет осуществить оба процесса аутентификации и продажи, используя одну транзакцию, он может использовать запрос SALE/SALE3D который включает в себя обе транзакции авторизация + продажа (AUTH/AUTH3D + SALE).

  9. После того как Мерчант предоставил товары и услуги держателю карты, необходимо отправить запрос с типом - SETTLE (зависит от выбранного схемы) для того, чтобы завершить траназкции через систему Genome Gateway, используя при этом референс транзакции авторизации. Запрос должен включать в себя поле кода аутентификации для проверки подлинности сообщения.

  10. Genome Gateway валидирует входящий запрос на завершение транзакции в банке. На данном этапе сумма транзакции списывается со счета держателя карты и зачисляется на счет мерчанта. Gateway отправляет ответ мерчанта о результате совершенного действия.

  11. Если мерчант не может выполнить обязательства перед держателем карты или если держатель карты отменяет заказ на этапе, разрешенном мерчантом, мерчанту необходимо отправить запрос VOID для отмены ожидающей транзакции или запрос REFUND для завершения транзакции. Система мерчанта отправляет данное сообщение непосредственно напрямую Genome Gateway API.

  12. Gateway проверяет входящий запрос, производит отмену ожидающих транзакций на стороне Gateway или запрашивает средства из банка для завершенной транзакции, в случае если это рефанд. Данный этап может включать передачу денежных средств со счета мерчанта обратно на счет держателя карты. Gateway отправляет ответ системе мерчанта в виде соответствующего документа.

    Mерчант может проверить статус транзакции на любом из этапов, отправив запрос CHECK Genome Gateway API.

  13. Для шифрования данных платежной карты, мерчант может отправить запрос TOKENIZE Genome Gateway API, чтобы зашифровать номер кредитной карты и получить зашифрованные данные.

Тестовые кредитные карты

Список тестовых кредитных карт представлен ниже:

Бренд Номер Срок истичения CVV код
Visa 4111111111111111 10 / 2022 123
Mastercard 5191330000004415 10 / 2022 123
Visa (3Ds) 4012000300001003 10 / 2022 123
Mastercard (3Ds) 5191330000004415 10 / 2022 123
American Express 371449635398431 10 / 2022 1234
Discover 6011111111111117 10 / 2022 123
Diners Club 30569309025904 10 / 2022 123
JCB 3530111333300000 10 / 2022 123

Дополнение: * Срок истичения службы карты можно вводить любой, главное, чтоб во время тестов дата была валидной. * Для CVV кода подойдет любой 3-х значный набор цифр, только для American Express - будет 4-х значный.

Транзакция Auth

Пример AUTH запроса:

https://gateway.genome.eu/api/cc

"Content-type: application/json" --data

{
    "api_version":1,
    "merchant_account":"Test Account",
    "merchant_password":"Test password",
    "transaction_unique_id":"myTransactioID",
    "transaction_type":"AUTH",
    "amount":19.99,
    "currency":"USD",
    "card_number":"4111111111111111",
    "card_exp_month":"05",
    "card_exp_year":"2016",
    "cvv":"111",
    "first_name":"John",
    "last_name":"Doe",
    "card_holder":"John Doe",
    "address":"123 Street name.",
    "city":"City Name",
    "zip":"02001",
    "country":"USA",
    "user_phone":"123456789",
    "user_email":"test@test.com",
    "user_ip":"127.0.0.1"
}

Запросы транзакций должны быть выполнены при помощи метода HTTP POST с использованием следующих HTTP  хедеров:

Accept: application/json,
Content-type: application/json.
Запрос должен быть в JSON формате.

Назначение: используется для блокировки суммы транзакции на счете держателя карты с использованием полной информации о платежной карте.

Параметры запроса:

Имя параметра Тип Объязательное Правила Пример
api_version float/string Да maxLength: { max: 32 } 1
merchant_account string Да minLength: { min: 6 }, maxLength: { max: 32 } Testshop.com
merchant_password string Да minLength: { min: 6 }, maxLength: { max: 32 } testpassword
transaction_unique_id string Да minLength: { min: 6 }, maxLength: { max: 32 } NwAkrkcPAmEcGzghnBwMeDRpXAPFsINg
transaction_type string Да validTransType, enum: { values: [”AUTH”]} AUTH
amount float Да float, maxLength: [0 - 9999999999.999] 5800
currency string Да length: { size: 3 }, ISO 4217 (alfa-3) GBP
card_number string Да minLength: { min: 13 }, maxLength: { max: 19 } only digits, Luhn algorithm 4864369454425300
card_exp_month string Да length: { size: 2 }, only digits 05
card_exp_year string Да length: { size: 4 }, only digits 2016
cvv string Нет minLength: { min: 3}, maxLength: { max: 4 }, only digits 911
first_name string Да minLength: { min: 1}, maxLength: { max: 32 } Card
last_name string Да minLength: { min: 1 }, maxLength: { max: 32 } Holder
card_holder string Да minLength: { min: 2 }, maxLength: { max: 32 } Card Holder
address string Нет minLength: { min: 2 } maxLength: { max: 32 } Billing address
city string Нет minLength: { min: 2 }, maxLength: { max: 32 } New Castle
state string Нет minLength: { min: 1 }, maxLength: { max: 32 } Texas
zip string Да minLength: { min: 2 }, maxLength: { max: 10 } 235467
country string Да minLength: { min: 2 }, maxLength: { max: 3 }, ISO 3166-1 alpha-3 GBR
user_phone string Нет minLength: { min: 7 }, maxLength: { max: 15 } 380111111111
user_email string Да minLength: { min: 6 }, maxLength: { max: 255 }, valid email 14848ff0308f8a396041ddde45de5f8a@gmail.com
user_ip string Да Ipv4Address 192.168.0.1
merchant_user_id string Нет maxLength: { max: 32 } 6d4a5d94821279725ecb3b0da9319d9b
merchant_domain_name string Нет maxLength: { max: 255 } vertu.com
merchant_affiliate_id string Нет maxLength: { max: 255 } 1234
merchant_product_name string Нет maxLength: { max: 255 } Chips
descriptor_merchant string Нет maxLength: { max: 255 } merchant.com
descriptor_phone string Нет maxLength: { max: 255 } 180012345678
pares string Нет NotEmptyString ABJASDKA+SDKAJ/SGDSAD

Пример AUTH ответа в формате JSON:

{
    "api_version":1,
    "merchant_account":"test_account",
    "sessionid":"543e2136-d46c-4d7d-a3b3-075cf9af6dea",
    "transaction_unique_id":"myUniqId1",
    "token":"5524fa52-75d8-4c7a-84ec-039d3097ab6f",
    "reference":" ATFF0000000039FDAEEF",
    "timestamp":1408001694,
    "authcode":"authcode_1544565466.22",
    "status":"error",
    "code":3100,
    "message":"Decline"
}

Параметры ответа:

Имя параметра Тип Объязательное Правила Пример
api_version float Да maxLength: { max: 32 } 1
merchant_account string Да minLength: { min: 6 }, maxLength: { max: 32 } Testshop.com
sessionid string Да maxLength: { max: 36 } 53ec668b-c838-44b8-86f2-5c678ae9e3fc
transaction_unique_id string Да minLength: { min: 1 } maxLength: { max: 32 } NwAkrkcPAmEcGzghnBwMeDRpXAPFsINg
token string Да length: { size: 36 } 14848ff0308f8a396041ddde45de5f8ffffa
reference string Да length: { size: 20 } ATFF1235432423
timestamp string Да unix timestamp 1408001694
authсode string Да maxLength: { max: 24 } 1111513
status string Да { SUCCESS, DECLINE, ERROR } SUCCESS
code numeric Да Returns response code for the transaction Response codes table
message string Да Returns explanation of the response code Response codes table

После того, как транзакция AUTH будет отработана, мерчанту необходимо осуществить одну из следующих транзакций:

Транзакция Auth (с токеном):

Пример запроса AUTH (с токеном):

"Content-type: application/json" --data

{
    "api_version":1,
    "merchant_account":"your_merchant_account",
    "merchant_password":"merchant_password",
    "transaction_unique_id":"auth_with_token001",
    "transaction_type":"AUTH",
    "amount":19.99,
    "currency":"USD",
    "first_name":"John",
    "last_name":"Doe",
    "card_holder":"John Doe",
    "address":"123 Street name.",
    "city":"City Name",
    "zip":"02001",
    "country":"USA",
    "user_phone":"123456789",
    "user_email":"test@test.com",
    "user_ip":"127.0.0.1",
    "token":"5524fa52-75d8-4c7a-84ec-039d3097ab6f"
}

Назначение: Интерфейс используется для блокировки суммы на счете карты с использованием billtoken.

Параметры запроса:

Имя параметра Тип Объязательное Правила Пример
api_version float/string Да maxLength: { max: 32 } 1
merchant_account string Да minLength: { min: 6 }, maxLength: { max: 32 } Testshop.com
merchant_password string Да minLength: { min: 6 }, maxLength: { max: 32 } testpassword
transaction_unique_id string Да minLength: { min: 6 }, maxLength: { max: 32 } NwAkrkcPAmEcGzghnBwMeDRpXAPFsINg
transaction_type string Да validTransType, enum: { values: [”AUTH”]} AUTH
amount float Да float, maxLength: [0 - 9999999999.999] 5800
currency string Да length: { size: 3 }, ISO 4217(alfa-3) GBP
cvv string Нет minLength: { min: 3}, maxLength: { max: 4 }, only digits 911
first_name string Да minLength: { min: 1}, maxLength: { max: 32 } Card
last_name string Да minLength: { min: 1 }, maxLength: { max: 32 } Holder
card_holder string Да minLength: { min: 2 }, maxLength: { max: 32 } Card Holder
address string Нет minLength: { min: 2 } maxLength: { max: 32 } Billing address
city string Нет minLength: { min: 2 }, maxLength: { max: 32 } New Castle
state string Нет minLength: { min: 1 }, maxLength: { max: 32 } Texas
zip string Да minLength: { min: 2 }, maxLength: { max: 10 } 235467
country string Да minLength: { min: 2 }, maxLength: { max: 3 }, ISO 3166-1 alpha-3 GBR
user_phone string Нет minLength: { min: 7 }, maxLength: { max: 15 } 380111111111
user_email string Да minLength: { min: 6 }, maxLength: { max: 255 }, valid email 14848ff0308f8a396041ddde45de5f8a@gmail.com
user_ip string Да Ipv4Address 192.168.0.1
merchant_user_id string Нет maxLength: { max: 32 } 6d4a5d94821279725ecb3b0da9319d9b
merchant_domain_name string Нет maxLength: { max: 255 } vertu.com
merchant_affiliate_id string Нет maxLength: { max: 255 } 1234
merchant_product_name string Нет maxLength: { max: 255 } Chips
descriptor_merchant string Нет maxLength: { max: 255 } merchant.com
descriptor_phone string Нет maxLength: { max: 255 } 180012345678
pares string Нет NotEmptyString ABJASDKA+SDKAJ/SGDSAD
token string Да length: { size: 36 } 14848ff0308f8a396041ddde45de5f8ffffa

Пример ответа AUTH (с токеном) в JSON формате:

{
    "api_version":1,
    "merchant_account":"your_merchant_account",
    "sessionid":"543e2136-d46c-4d7d-a3b3-075cf9af6dea",
    "transaction_unique_id":"auth_with_token001",
    "token":"5524fa52-75d8-4c7a-84ec-039d3097ab6f",
    "reference":" ATFF0000000039FDAEEF",
    "timestamp":1408001694,
    "authcode":"authcode_1544565466.22",
    "status":"error",
    "code":3100,
    "message":"Decline"
}

Параметры ответа:

Имя параметра Тип Объязательное Правила Пример
api_version float Да maxLength: { max: 32 } 1
merchant_account string Да minLength: { min: 6 }, maxLength: { max: 32 } Testshop.com
sessionid string Да maxLength: { max: 36 } 53ec668b-c838-44b8-86f2-5c678ae9e3fc
transaction_unique_id string Да minLength: { min: 1 } maxLength: { max: 32 } NwAkrkcPAmEcGzghnBwMeDRpXAPFsINg
token string Да length: { size: 36 } 14848ff0308f8a396041ddde45de5f8ffffa
reference string Да length: { size: 20 } ATFF1235432423
timestamp string Да unix timestamp 1408001694
authсode string Да maxLength: { max: 24 } 1111513
status string Да { SUCCESS, DECLINE, ERROR } SUCCESS
code numeric Да Returns response code for the transaction Response codes table
message string Да Returns explanation of the response code Response codes table

После того, как транзакция AUTH будет обработана, мерчант, в зависимости от требований бизнеса, может, но не обязан, осуществить следующие транзакции:

Транзакция Auth3D

Пример AUTH3D запроса:

"Content-type: application/json" --data 

{
    "api_version":1,
    "merchant_account":"your_merchant_account",
    "merchant_password":"account_password",
    "transaction_unique_id":"auth3d_request001",
    "transaction_type":"AUTH3D",
    "amount":19.99,
    "currency":"USD",
    "card_number":"4012000300001003",
    "card_exp_month":"05",
    "card_exp_year":"2016",
    "cvv": "111",
    "first_name":"John",
    "last_name":"Doe",
    "card_holder":"John Doe",
    "address":"123 Street name.",
    "city":"City Name",
    "zip":"02001",
    "country":"USA",
    "user_phone":"123456789",
    "user_email":"test@test.com",
    "user_ip":"127.0.0.1"
}

Назначение: позволяет проверить возможность использования 3DSecure для данной карты. ECI код будет передан в ответе, с целью описания причин (например, в негативном случае), что карта не поддерживает данный тип.

В позитивном случае Мерчант может использовать транзакцию SALE с обязательными параметрами pares и reference, которые являются обязательными для передачи в данном виде запроса.

Возможный вариант использования транзакций AUTH3D и SALE (full cc) описан ниже:

Параметры запроса:

Имя параметра Тип Объязательное Правила Пример
api_version float/string Да maxLength: { max: 32 } 1
merchant_account string Да minLength: { min: 6 }, maxLength: { max: 32 } Testshop.com
merchant_password string Да minLength: { min: 6 }, maxLength: { max: 32 } testpassword
transaction_unique_id string Да minLength: { min: 6 }, maxLength: { max: 32 } NwAkrkcPAmEcGzghnBwMeDRpXAPFsINg
transaction_type string Да validTransType, enum: { values: [”AUTH3D”]} AUTH3D
amount float Да float, maxLength: [0 - 9999999999.999] 5800
currency string Да length: { size: 3 }, ISO 4217 (alfa-3) GBP
card_number string Да minLength: { min: 13 }, maxLength: { max: 19 } only digits, Luhn algorithm
  • 4012000300001003
  • 5191330000004415
card_exp_month string Да length: { size: 2 }, only digits 05
card_exp_year string Да length: { size: 4 }, only digits 2016
cvv string Нет minLength: { min: 3}, maxLength: { max: 4 }, only digits 911
first_name string Да minLength: { min: 1}, maxLength: { max: 32 } Card
last_name string Да minLength: { min: 1 }, maxLength: { max: 32 } Holder
card_holder string Да minLength: { min: 2 }, maxLength: { max: 32 } Card Holder
address string Нет minLength: { min: 2 } maxLength: { max: 32 } Billing address
city string Нет minLength: { min: 2 }, maxLength: { max: 32 } New Castle
state string Нет minLength: { min: 1 }, maxLength: { max: 32 } Texas
zip string Да minLength: { min: 2 }, maxLength: { max: 10 } 235467
country string Да minLength: { min: 2 }, maxLength: { max: 3 }, ISO 3166-1 alpha-3 GBR
user_phone string Нет minLength: { min: 7 }, maxLength: { max: 15 } 380111111111
user_email string Да minLength: { min: 6 }, maxLength: { max: 255 }, valid email 14848ff0308f8a396041ddde45de5f8a@gmail.com
user_ip string Да Ipv4Address 192.168.0.1
merchant_user_id string Нет maxLength: { max: 32 } 6d4a5d94821279725ecb3b0da9319d9b
merchant_domain_name string Нет maxLength: { max: 255 } vertu.com
merchant_affiliate_id string Нет maxLength: { max: 255 } 1234
merchant_product_name string Нет maxLength: { max: 255 } Chips
descriptor_merchant string Нет maxLength: { max: 255 } merchant.com
descriptor_phone string Нет maxLength: { max: 255 } 180012345678

Пример ответа в формате JSON:

{
  "api_version": 1,
  "merchant_account": "your_merchant_account",
  "sessionid": "81g47d-7avb-59103914-14be75ef73f-136e",
  "transaction_unique_id": "auth3d_request001",
  "token": "5814f79a-c8fc-40c2-8161-4e0u68cc13ed",
  "reference": "A3FF000000439730A8E",
  "timestamp": 1494235313,
  "authcode": "",
  "pareq": "eyJyZWZlcmVuY2UiOiJBM0ZGMDAwMDAwMDM5NzMwQTgwRVhYMDEiLCJ0aW1lIjoxE0LjU1NTh9",
  "acs_url": "https://callback-service.genome.eu/emitent/",
  "eci": 5,
  "status": "success",
  "code": 0,
  "message": "Transaction processed successfully"
}

Параметры ответа:

Имя параметра Тип Объязательное Правила Пример
api_version float Да maxLength: { max: 32 } 1
merchant_account string Да minLength: { min: 6 }, maxLength: { max: 32 } Testshop.com
sessionid string Да maxLength: { max: 36 } 53ec668b-c838-44b8-86f2-5c678ae9e3fc
transaction_unique_id string Да maxLength: { max: 32 }, minLength: { min: 1 } NwAkrkcPAmEcGzghnBwMeDRpXAPFsINg
token string Да length: { size: 36 } 14848ff0308f8a396041ddde45de5f8ffffa
reference string Да length: { size: 20 } ATFF1235432423
timestamp string Да unix timestamp 1408001694
authcode string Да maxLength: { max: 24 } 1111513
eci numeric Нет { 1, 2, 5, 6, 7 } 7
pareq string Нет maxLength: { max: 65535 } eJxVUctuwjAQ/JWIK1LsvAqNNpZSEA8BLS1UhWMwFolC4sR2Wvj72jQpre TDzuzueDQL21QwNt4w2ghGYMWkTE7Myo5Rr5AНет+gRWMdvrCbwyYTMeEkcG9s
acs_url string Нет maxLength: { max: 255 } https://genome.eu:9443/PIT/ATS
status string Да { SUCCESS, DECLINE, ERROR } SUCCESS
code numeric Да Returns response code for the transaction Response codes table
message string Да Returns explanation of the response code Response codes table

Пример формы редиректа после AUTH3D:


<form id="acsform" method="POST" action="<AcsUrl>">
        <input name="PaReq" type="hidden" value="<PaReq>">
        <input name="TermUrl" type="hidden" value="<TermUrl>">
        <input name="MD" type="hidden" value="">
    </form>
    <script type="text/javascript">
        document.getElementById('acsform').submit();
    </script>

После того, как транзакция AUTH3D была обработана, мерчант, в зависимости от требований бизнеса, может, но не обязан, осуществить следующие типы транзакций:

Транзакция Auth3D c токеном

Пример AUTH3D запроса (с токеном):

"Content-type: application/json" --data 

{
    "api_version":1,
    "merchant_account":"your_merchant_account",
    "merchant_password":"account_password",
    "transaction_unique_id":"auth3d_token001",
    "transaction_type":"AUTH3D",
    "amount":19.99,
    "currency":"USD",
    "first_name":"John",
    "last_name":"Doe",
    "card_holder":"John Doe",
    "address":"123 Street name.",
    "city":"City Name",
    "zip":"02001",
    "country":"USA",
    "user_phone":"123456789",
    "user_email":"test@test.com",
    "user_ip":"127.0.0.1",
    "token":"55a28a26-92e8-4026-bdc8-2e2f58a0e038"
}

Назначение: используется для проверки возможности провести 3DSecure транзакцию использованием токена карты. В положительном случае, мерчант может использовать запрос SALE. В противном случае, для объяснения действий будет отправлен ECI код.

Параметры запроса:

Имя параметра Тип Объязательное Правила Пример
api_version float/string Да maxLength: { max: 32 } 1
merchant_account string Да minLength: { min: 6 }, maxLength: { max: 32 } Testshop.com
merchant_password string Да minLength: { min: 6 }, maxLength: { max: 32 } testpassword
transaction_unique_id string Да minLength: { min: 6 }, maxLength: { max: 32 } NwAkrkcPAmEcGzghnBwMeDRpXAPFsINg
transaction_type string Да validTransType, enum: { values: [”AUTH3D”]} AUTH3D
amount float Да float, maxLength: [0 - 9999999999.999] 5800
currency string Да length: { size: 3 }, ISO 4217 (alfa-3) GBP
cvv string Нет minLength: { min: 3}, maxLength: { max: 4 }, only digits 911
first_name string Да minLength: { min: 1}, maxLength: { max: 32 } Card
last_name string Да minLength: { min: 1 }, maxLength: { max: 32 } Holder
card_holder string Да minLength: { min: 2 }, maxLength: { max: 32 } Card Holder
address string Нет minLength: { min: 2 } maxLength: { max: 32 } Billing address
city string Нет minLength: { min: 2 }, maxLength: { max: 32 } New Castle
state string Нет minLength: { min: 1 }, maxLength: { max: 32 } Texas
zip string Да minLength: { min: 2 }, maxLength: { max: 10 } 235467
country string Да minLength: { min: 2 }, maxLength: { max: 3 }, ISO 3166-1 alpha-3 GBR
user_phone string Нет minLength: { min: 7 }, maxLength: { max: 15 } 380111111111
user_email string Да minLength: { min: 6 }, maxLength: { max: 255 }, valid email 14848ff0308f8a396041ddde45de5f8a@gmail.com
user_ip string Да Ipv4Address 192.168.0.1
merchant_user_id string Нет maxLength: { max: 32 } 6d4a5d94821279725ecb3b0da9319d9b
merchant_domain_name string Нет maxLength: { max: 255 } vertu.com
merchant_affiliate_id string Нет maxLength: { max: 255 } 1234
merchant_product_name string Нет maxLength: { max: 255 } Chips
descriptor_merchant string Нет maxLength: { max: 255 } merchant.com
descriptor_phone string Нет maxLength: { max: 255 } 180012345678
token string Да length: { size: 36 } 14848ff0308f8a396041ddde45de5f8ffffa

Пример ответа AUTH3D (с токеном) в формате JSON:

{
  "api_version": 1,
  "merchant_account": "your_merchant_account",
  "sessionid": "81g47d-7avb-59103914-14be75ef73f-136e",
  "transaction_unique_id": "auth3d_token001",
  "token": "5814f79a-c8fc-40c2-8161-4e0u68cc13ed",
  "reference": "A3FF000000439730A8E",
  "timestamp": 1494235313,
  "authcode": "",
  "pareq": "eyJyZWZlcmVuY2UiOiJBM0ZGMDAwMDAwMDM5NzMwQTgwRVhYMDEiLCJ0aW1lIjoxE0jjU1NTF8",
  "acs_url": "https://callback-service.genome.eu/emitent/",
  "eci": 5,
  "status": "success",
  "code": 0,
  "message": "Transaction processed successfully"
}

Параметры ответа:

Имя параметра Тип Объязательное Правила Пример
api_version float Да maxLength: { max: 32 } 1
merchant_account string Да minLength: { min: 6 }, maxLength: { max: 32 } Testshop.com
sessionid string Да maxLength: { max: 36 } 53ec668b-c838-44b8-86f2-5c678ae9e3fc
transaction_unique_id string Да maxLength: { max: 32 }, minLength: { min: 1 } NwAkrkcPAmEcGzghnBwMeDRpXAPFsINg
toke string Да length: { size: 36 } 14848ff0308f8a396041ddde45de5f8ffffa
reference string Да length: { size: 20 } ATFF1235432423
timestamp string Да unix timestamp 1408001694
authcode string Да maxLength: { max: 24 } 1111513
eci numeric Нет { 1, 2, 5, 6, 7 } 7
pareq string Нет maxLength: { max: 65535 } eJxVUctuwjAQ/JWIK1LsvAqNNpZSEA8BLS1UhWMwFolC4sR2Wvj72jQpre TDzuzueDQL21QwNt4w2ghGYMWkTE7Myo5Rr5AНет+gRWMdvrCbwyYTMeEkcG9s
acs_url string Нет maxLength: { max: 255 } https://genome.eu:9443/PIT/ATS
status string Да { SUCCESS, DECLINE, ERROR } SUCCESS
code numeric Да Returns response code for the transaction Response codes table
message string Да Returns explanation of the response code Response codes table

Пример формы редиректа после AUTH3D:


    <form id="acsform" method="POST" action="<AcsUrl>">
        <input name="PaReq" type="hidden" value="<PaReq>">
        <input name="TermUrl" type="hidden" value="<TermUrl>">
        <input name="MD" type="hidden" value="">
    </form>
    <script type="text/javascript">
        document.getElementById('acsform').submit();
    </script>

После того, как транзакция AUTH3D была обработана, мерчант, в зависимости от требований бизнеса, может, но не обязан, осуществить следующие транзакции:

Транзакция SETTLE

Пример SETTLE запроса:

"Content-type: application/json" --data

{
    "api_version":1,
    "merchant_account":"your_merchant_account",
    "merchant_password":"account_password",
    "transaction_unique_id":"settle_request001",
    "transaction_type":"SETTLE",
    "amount":19.99,
    "currency":"USD",
    "reference":"ATFF0000000039FDAEC1"
}

Назначение: предназначена для подтверждения списания по предварительно авторизированной (с использованием AUTH) транзакции.

Параметры запроса:

Имя параметра Тип Объязательное Правила Пример
api_version float Да maxLength: { max: 32 } 1
merchant_account string Да minLength: { min: 6 } maxLength: { max: 32 } Testshop.com
merchant_password string Да minLength: { min: 6 }, maxLength: { max: 32 } testpassword
transaction_unique_id string Да minLength: { min: 6 }, maxLength: { max: 32 } NwAkrkcPAmEcGzghnBwMeDRpXAPFsINg
transaction_type string Да validTransType, enum: { values: ["SETTLE"]} SETTLE
amount float Да float, maxLength: [0 - 9999999999.999] 5800
currency string Да length: { size: 3 }, ISO 4217 (alfa-3) GBP
reference string Да length: { size: 20 } ATFF0000000039FDAEC1 референс AUTH или AUTH3D транзакции
merchant_domain_name string Нет maxLength: { max: 255} merchant.com
merchant_affiliate_id string Нет maxLength: { max: 255} 1
merchant_user_id string Нет maxLength: { max: 32} 6d4a5d94821279725ecb3b0da9319d9b
merchant_product_name string Нет maxLength: { max: 255} Test product
descriptor_merchant string Нет maxLength: { max: 255} merchant.com
descriptor_phone string Нет maxLength: { max: 255} 180012345678

Пример SETTLE ответа в формате JSON:

{
    "api_version":1,
    "merchant_account":"your_merchant_account",
    "sessionid":"543e2136-d46c-4d7d-a3b3-075cf9adkl21",
    "transaction_unique_id":"settle_request001",
    "token":"5524fa52-75d8-4c7a-84ec-039d3097ab6f",
    "reference":"STFF0000000039FDAEGG",
    "timestamp":1408001694,
    "authcode":"",
    "status":"success",
    "code":0,
    "message":"transaction processed successfully"
}

Параметры ответа:

Имя параметра Тип Объязательное Правила Пример
api_version float Да maxLength: { max: 32 } 1
merchant_account string Да minLength: { min: 6 } maxLength: { max: 32 } Testshop.com
sessionid string Да maxLength: { max: 36 } 53ec668b-c838-44b8-86f2-5c678ae9e3fc
token string Да length: { size: 36 } 14848ff0308f8a396041ddde45de5f8ffffa
authсode string Да maxLength: { max: 24 } 1111513
reference string Да length: { size: 20 } ATFF1235432423
transaction_unique_id string Да minLength: { min: 1 } maxLength: { max: 32 } NwAkrkcPAmEcGzghnBwMeDRpXAPFsINg
status string Да { SUCCESS, DECLINE, ERROR } SUCCESS
code numeric Да Returns response code of the transaction Response codes table
message string Да Returns explanation of the response code Response codes table
timestamp string Да unix timestamp 1408001694

После того, как транзакция SETTLE была обработана, мерчант, в зависимости от требований бизнеса, может, но не обязан, осуществить следующие транзакции:

Транзакция Sale

Пример SALE запроса:

"Content-type: application/json" --data

{
    "api_version":1,
    "merchant_account":"your_merchant_account",
    "merchant_password":"account_password",
    "transaction_unique_id":"sale_request001",
    "transaction_type":"SALE",
    "amount":10,
    "currency":"USD",
    "card_number":"4111111111111111",
    "card_exp_month":"05",
    "card_exp_year":"2018",
    "cvv":"121",
    "first_name":"John",
    "last_name":"Doe",
    "card_holder":"John Doe",
    "address":"123 Street name.",
    "city":"City Name",
    "zip":"02001",
    "country":"USA",
    "user_phone":"123456789",
    "user_email":"test@test.com",
    "user_ip":"127.0.0.1"
}

Назначение: используется для снятия средств с карты с использованием полной информации о кредитной карте.

Примечание: в случае с 3dsecure (после успешного AUTH3D), pares и reference должны быть обязательно переданы в запросе.

Параметры запроса:

Имя параметра Тип Объязательное Правила Пример
api_version float/string Да maxLength: { max: 32 } 1
merchant_account string Да minLength: { min: 6 }, maxLength: { max: 32 } Testshop.com
merchant_password string Да minLength: { min: 6 }, maxLength: { max: 32 } testpassword
transaction_unique_id string Да minLength: { min: 6 }, maxLength: { max: 32 } NwAkrkcPAmEcGzghnBwMeDRpXAPFsINg
transaction_type string Да validTransType, enum: { values: [”SALE”]} SALE
reference string Нет length: { size: 20 } Mandatory for 3Ds flow 14848ff0308f8a396041ddde45de5f8ffffa
amount float Да float, maxLength: [0 - 9999999999.999] 5800
currency string Да length: { size: 3 }, ISO 4217 (alfa-3) GBP
card_number string Да minLength: { min: 13 }, maxLength: { max: 19 } only digits, Luhn algorithm 4864369454425300
card_exp_month string Да length: { size: 2 }, only digits 05
card_exp_year string Да length: { size: 4 }, only digits 2016
cvv string Нет minLength: { min: 3}, maxLength: { max: 4 }, only digits 911
first_name string Да minLength: { min: 1}, maxLength: { max: 32 } Card
last_name string Да minLength: { min: 1 }, maxLength: { max: 32 } Holder
card_holder string Да minLength: { min: 2 }, maxLength: { max: 32 } Card Holder
address string Нет minLength: { min: 2 } maxLength: { max: 32 } Billing address
city string Нет minLength: { min: 2 }, maxLength: { max: 32 } New Castle
state string Нет minLength: { min: 1 }, maxLength: { max: 32 } Texas
zip string Да minLength: { min: 2 }, maxLength: { max: 10 } 235467
country string Да minLength: { min: 2 }, maxLength: { max: 3 }, ISO 3166-1 alpha-3 GBR
user_phone string Нет minLength: { min: 7 }, maxLength: { max: 15 } 380111111111
user_email string Да minLength: { min: 6 }, maxLength: { max: 255 }, valid email 14848ff0308f8a396041ddde45de5f8a@gmail.com
user_ip string Да Ipv4Address 192.168.0.1
merchant_user_id string Нет maxLength: { max: 32 } 6d4a5d94821279725ecb3b0da9319d9b
merchant_domain_name string Нет maxLength: { max: 255 } vertu.com
merchant_affiliate_id string Нет maxLength: { max: 255 } 1234
merchant_product_name string Нет maxLength: { max: 255 } Chips
descriptor_merchant string Нет maxLength: { max: 255 } merchant.com
descriptor_phone string Нет maxLength: { max: 255 } 180012345678
pares string Нет NotEmptyString, Mandatory for 3Ds flow ABJASDKA+SDKAJ/SGDSAD

Пример ответа по SALE запросу в формате JSON:

{
    "api_version":1,
    "merchant_account":"your_merchant_account",
    "sessionid":"543e2136-d46c-4d7d-a3b3-075cf9adkl01",
    "transaction_unique_id":"sale_request001",
    "token":"5524fa52-75d8-4c7a-84ec-039d3097ab6f",
    "reference":" SLFF0000000039FDAEAB",
    "timestamp":1408001694,
    "authcode":"",
    "status":"success",
    "code":0,
    "message":"transaction processed successfully"
}

Параметр ответа:

Имя параметра Тип Объязательное Правила Пример
api_version float Да maxLength: { max: 32 } 1
merchant_account string Да minLength: { min: 6 }, maxLength: { max: 32 } Testshop.com
sessionid string Да maxLength: { max: 36 } 53ec668b-c838-44b8-86f2-5c678ae9e3fc
transaction_unique_id string Да minLength: { min: 1 } maxLength: { max: 32 } NwAkrkcPAmEcGzghnBwMeDRpXAPFsINg
token string Да length: { size: 36 } 14848ff0308f8a396041ddde45de5f8ffffa
reference string Да length: { size: 20 } ATFF1235432423
timestamp string Да unix timestamp 1408001694
authсode string Да maxLength: { max: 24 } 1111513
status string Да { SUCCESS, DECLINE, ERROR } SUCCESS
code numeric Да Returns response code for the transaction Response codes table
message string Да Returns explanation of the response code Response codes table

После того, как транзакция SALE была обработана, мерчант, в зависимости от требований бизнеса, может, но не обязан, осуществить следующие транзакции:

Транзакция Sale (с токеном):

Пример SALE запроса (с токеном):

"Content-type: application/json" --data

{
    "api_version":1,
    "merchant_account":"your_merchant_account",
    "merchant_password":"account_password",
    "transaction_unique_id":"sale_token001",
    "transaction_type":"SALE",
    "amount":10,
    "currency":"USD",
    "first_name":"John",
    "last_name":"Doe",
    "card_holder":"John Doe",
    "address":"123 Street name.",
    "city":"City Name",
    "zip":"02001",
    "country":"USA",
    "user_phone":"123456789",
    "user_email":"test@test.com",
    "user_ip":"127.0.0.1",
    "token":"5524fa52-75d8-4c7a-84ec-039d3097ab6f"
}

Назначение: используется для снятия средств с карты с использованием billtoken.

параметры запроса:

Имя параметра Тип Объязательное Правила Пример
api_version float/string Да maxLength: { max: 32 } 1
merchant_account string Да minLength: { min: 6 }, maxLength: { max: 32 } Testshop.com
merchant_password string Да minLength: { min: 6 }, maxLength: { max: 32 } testpassword
transaction_unique_id string Да minLength: { min: 6 }, maxLength: { max: 32 } NwAkrkcPAmEcGzghnBwMeDRpXAPFsINg
transaction_type string Да validTransType, enum: { values: [”SALE”]} SALE
amount float Да float, maxLength: [0 - 9999999999.999] 5800
currency string Да length: { size: 3 }, ISO 4217 (alfa-3) GBP
cvv string Нет minLength: { min: 3}, maxLength: { max: 4 }, only digits 911
first_name string Да minLength: { min: 1}, maxLength: { max: 32 } Card
last_name string Да minLength: { min: 1 }, maxLength: { max: 32 } Holder
card_holder string Да minLength: { min: 2 }, maxLength: { max: 32 } Card Holder
address string Нет minLength: { min: 2 } maxLength: { max: 32 } Billing address
city string Нет minLength: { min: 2 }, maxLength: { max: 32 } New Castle
state string Нет minLength: { min: 1 }, maxLength: { max: 32 } Texas
zip string Да minLength: { min: 2 }, maxLength: { max: 10 } 235467
country string Да minLength: { min: 2 }, maxLength: { max: 3 }, ISO 3166-1 alpha-3 GBR
user_phone string Нет minLength: { min: 7 }, maxLength: { max: 15 } 380111111111
user_email string Да minLength: { min: 6 }, maxLength: { max: 255 }, valid email 14848ff0308f8a396041ddde45de5f8a@gmail.com
user_ip string Да Ipv4Address 192.168.0.1
merchant_user_id string Нет maxLength: { max: 32 } 6d4a5d94821279725ecb3b0da9319d9b
merchant_domain_name string Нет maxLength: { max: 255 } vertu.com
merchant_affiliate_id string Нет maxLength: { max: 255 } 1234
merchant_product_name string Нет maxLength: { max: 255 } Chips
descriptor_merchant string Нет maxLength: { max: 255 } merchant.com
descriptor_phone string Нет maxLength: { max: 255 } 180012345678
token string Да length: { size: 36 } 14848ff0308f8a396041ddde45de5f8ffffa

Пример ответа по запросу SALE (с токеном) в формате JSON:

{
    "api_version":1,
    "merchant_account":"your_merchant_account",
    "sessionid":"543e2136-d46c-4d7d-a3b3-075cf9adkl21",
    "transaction_unique_id":"sale_token001",
    "token":"5524fa52-75d8-4c7a-84ec-039d3097ab6f",
    "reference":"SLFF0000000039FDAEGG",
    "timestamp":1408001694,
    "authcode":"",
    "status":"success",
    "code":0,
    "message":"transaction processed successfully"
}

Параметры ответа:

Имя параметра Тип Объязательное Правила Пример
api_version float Да maxLength: { max: 32 } 1
merchant_account string Да minLength: { min: 6 }, maxLength: { max: 32 } Testshop.com
sessionid string Да maxLength: { max: 36 } 53ec668b-c838-44b8-86f2-5c678ae9e3fc
transaction_unique_id string Да minLength: { min: 1 } maxLength: { max: 32 } NwAkrkcPAmEcGzghnBwMeDRpXAPFsINg
token string Да length: { size: 36 } 14848ff0308f8a396041ddde45de5f8ffffa
reference string Да length: { size: 20 } SLFF1235432423
timestamp string Да unix timestamp 1408001694
authсode string Да maxLength: { max: 24 } 1111513
status string Да { SUCCESS, DECLINE, ERROR } SUCCESS
code numeric Да Returns response code for the transaction Response codes table
message string Да Returns explanation of the response code Response codes table

После того, как транзакция SALE была обработана, мерчант, в зависимости от требований бизнеса, может, но не обязан, осуществить следующие транзакции:

Транзакция Sale3D

Пример SALE3D запроса:

"Content-type: application/json" --data

{
    "api_version":1,
    "merchant_account":"your_merchant_account",
    "merchant_password":"account_password",
    "transaction_unique_id":"sale3D_request001",
    "transaction_type":"SALE3D",
    "amount":10,
    "currency":"USD",
    "card_number":"5191330000004415",
    "card_exp_month":"05",
    "card_exp_year":"2018",
    "cvv":"121",
    "first_name":"John",
    "last_name":"Doe",
    "card_holder":"John Doe",
    "address":"123 Street name.",
    "city":"City Name",
    "zip":"02001",
    "country":"USA",
    "user_phone":"123456789",
    "user_email":"johndoe@test.com",
    "user_ip":"127.0.0.1",
    "callback_url":"https://test.com/callback",
    "redirect_url":"https://test.com/redirect"
}

*Назначение: * используется для проверки возможности осуществить 3DSecure транзакцию. Код ECI будет отправлен для объяснения причин транзакции (например, в отрицательном случае). В положительном случае, на стороне Genome Gateway автоматически запускается запрос SALE.

Параметры запроса:

Имя параметра Тип Объязательное Правила Пример
api_version float/string Да maxLength: { max: 32 } 1
merchant_account string Да minLength: { min: 6 }, maxLength: { max: 32 } Testshop.com
merchant_password string Да minLength: { min: 6 }, maxLength: { max: 32 } testpassword
transaction_unique_id string Да minLength: { min: 6 }, maxLength: { max: 32 } NwAkrkcPAmEcGzghnBwMeDRpXAPFsINg
transaction_type string Да validTransType, enum: { values: [”SALE3D”]} SALE3D
amount float Да float, maxLength: [0 - 9999999999.999] 5800
currency string Да length: { size: 3 }, ISO 4217 (alfa-3) GBP
card_number string Да minLength: { min: 13 }, maxLength: { max: 19 } only digits, Luhn algorithm
  • 4012000300001003
  • 5191330000004415
card_exp_month string Да length: { size: 2 }, only digits 05
card_exp_year string Да length: { size: 4 }, only digits 2016
cvv string Нет minLength: { min: 3}, maxLength: { max: 4 }, only digits 911
first_name string Да minLength: { min: 1}, maxLength: { max: 32 } Card
last_name string Да minLength: { min: 1 }, maxLength: { max: 32 } Holder
card_holder string Да minLength: { min: 2 }, maxLength: { max: 32 } Card Holder
address string Нет minLength: { min: 2 } maxLength: { max: 32 } Billing address
city string Нет minLength: { min: 2 }, maxLength: { max: 32 } New Castle
state string Нет minLength: { min: 1 }, maxLength: { max: 32 } Texas
zip string Да minLength: { min: 2 }, maxLength: { max: 10 } 235467
country string Да minLength: { min: 2 }, maxLength: { max: 3 }, ISO 3166-1 alpha-3 GBR
user_phone string Нет minLength: { min: 7 }, maxLength: { max: 15 } 380111111111
user_email string Да minLength: { min: 6 }, maxLength: { max: 255 }, valid email 14848ff0308f8a396041ddde45de5f8a@gmail.com
user_ip string Да Ipv4Address 192.168.0.1
merchant_user_id string Нет maxLength: { max: 32 } 6d4a5d94821279725ecb3b0da9319d9b
merchant_domain_name string Нет maxLength: { max: 255 } vertu.com
merchant_affiliate_id string Нет maxLength: { max: 255 } 1234
merchant_product_name string Нет maxLength: { max: 255 } Chips
descriptor_merchant string Нет maxLength: { max: 255 } merchant.com
descriptor_phone string Нет maxLength: { max: 255 } 180012345678
callback_url string Да maxLength: { max: 255 } https://testshop.com/success
redirect_url string Да maxLength: { max: 255 } http://testshop.com/redirect

Пример ответа на запрос SALE3D в формате JSON:

{
    "api_version":1,
    "merchant_account":"your_merchant_account",
    "sessionid":"543e2136-d46c-4d7d-a3b3-075cf9adkl21",
    "transaction_unique_id":"sale3D_request001",
    "token":"5524fa52-75d8-4c7a-84ec-039d3097ab6g",
    "reference":" S3FF0000000039FDAEGG",
    "timestamp":1408001694,
    "authcode": "",
    "eci": 5,
    "acs_url": "https://callback-service.genome.eu/emitent/",
    "authcode":"",
    "status":"success",
    "code":0,
    "message":"transaction processed successfully"
}

Параметры ответа:

Имя параметра Тип Объязательное Правила Пример
api_version float Да maxLength: { max: 32 } 1
merchant_account string Да minLength: { min: 6 }, maxLength: { max: 32 } Testshop.com
sessionid string Да maxLength: { max: 36 } 53ec668b-c838-44b8-86f2-5c678ae9e3fc
transaction_unique_id string Да maxLength: { max: 32 }, minLength: { min: 1 } NwAkrkcPAmEcGzghnBwMeDRpXAPFsINg
token string Да length: { size: 36 } 14848ff0308f8a396041ddde45de5f8ffffa
reference string Да length: { size: 20 } ATFF1235432423
timestamp string Да unix timestamp 1408001694
authcode string Да maxLength: { max: 24 } 1111513
eci numeric Нет { 1, 2, 5, 6, 7 } 7
acs_url string Нет maxLength: { max: 255 } https://genome.eu:9443/PIT/ATS
status string Да { SUCCESS, DECLINE, ERROR } SUCCESS
code numeric Да Returns response code for the transaction Response codes table
message string Да Returns explanation of the response code Response codes table

После того, как транзакция SALE3D была обработана, мерчант, в зависимости от требований бизнеса, может, но не обязан, осуществить следующие транзакции:

При использовании типа SALE3D Genome автоматически инициирует транзакцию SALE и отправляет ответ на предварительно указанный Мерчантом URL (Callback).

Пример callback ответа на SALE3D запрос в формате JSON:

{
    "api_version":1,
    "merchant_account":"your_merchant_account",
    "sessionid":"543e2136-d46c-4d7d-a3b3-075cf9adkl21",
    "transaction_unique_id":"sale3D_request001",
    "token":"5524fa52-75d8-4c7a-84ec-039d3097ab6g",
    "reference":" S3FF0000000039FDAEGG",
    "timestamp":1408001694,
    "authcode": "",
    "status":"success",
    "code":0,
    "message":"transaction processed successfully",
    "signature":"7be7f8abad70931c177bedb88993405ab88aee79e0a54b8411f02eadc27f3476"
}

Параметры ответа по SALE3D транзакции:

Имя параметра Тип Объязательное Правила Пример
api_version float Да maxLength: { max: 32 } 1
merchant_account string Да minLength: { min: 6 }, maxLength: { max: 32 } Testshop.com
sessionid string Да maxLength: { max: 36 } 55882952-a344-40ce-af84-173c025bd8bd
transaction_unique_id string Да maxLength: { max: 32 }, minLength: { min: 1 } 1434986821.1471529083
token string Да length: { size: 36 } 55880d83-3fb0-43eb-a18f-173c025bd8bd
reference string Да length: { size: 20 } SLFF00000000395DA2C3
timestamp string Да unix timestamp 1434986844
authcode string Да maxLength: { max: 24 } 1434986845.693
status string Да { SUCCESS, DECLINE, ERROR } SUCCESS
code numeric Да Returns response code for the transaction Response codes table
message string Да Returns explanation of the response code Response codes table
signature * string Да maxLength: { max: 32 } 7be7f8abad70931c177bedb88993405ab88aee79e0a54b8411f02eadc27f3476

* Поле подписи (signature) содержит хэш данных ответа и должно быть провалидированно на стороне Мерчанта, используя следующий алгоритм хеширования для сортируемых в алфавитном порядке и каскадных полей данных: * hash(‘sha256’,’($key[0]=$val[0].$key[n]=$val[n].$key[n+1]=$val[n+1].$secret’), where $key equals field name, $val equals field value, $secret equals hashed using sha512 Merchant account password value.

Мерчант, в зависимости от требований бизнеса, может, но не обязан, осуществить следующие транзакции:

Транзакция Sale3D c токеном

Пример SALE3D запроса (с токеном):

"Content-type: application/json" --data

{
    "api_version":1,
    "merchant_account":"your_merchant_account",
    "merchant_password":"account_password",
    "transaction_unique_id":"sale3D_token001",
    "transaction_type":"SALE3D",
    "amount":10,
    "currency":"USD",
    "first_name":"John",
    "last_name":"Doe",
    "card_holder":"John Doe",
    "address":"123 Street name.",
    "city":"City Name",
    "zip":"02001",
    "country":"USA",
    "user_phone":"123456789",
    "user_email":"johndoe@test.com",
    "user_ip":"127.0.0.1",
    "token":"5524fa52-75d8-4c7a-84ec-039d3097ab6g",
    "callback_url":"https://test.com/callback",
    "redirect_url":"https://test.com/redirect"
}

Назначение: используется для проверки возможности использовать для карты 3DSecure транзакцию. Код ECI будет отправлен для объяснения причин транзакции (например, в отрицательном случае). В положительном случае, на стороне Genome Gateway автоматически запускается запрос SALE. Ответ на запрос SALE будет отправлен на callback URL Мерчанта.

Параметры запроса:

Имя параметра Тип Объязательное Правила Пример
api_version float/string Да maxLength: { max: 32 } 1
merchant_account string Да minLength: { min: 6 }, maxLength: { max: 32 } Testshop.com
merchant_password string Да minLength: { min: 6 }, maxLength: { max: 32 } testpassword
transaction_unique_id string Да minLength: { min: 6 }, maxLength: { max: 32 } NwAkrkcPAmEcGzghnBwMeDRpXAPFsINg
transaction_type string Да validTransType, enum: { values: [”SALE3D”]} SALE3D
amount float Да float, maxLength: [0 - 9999999999.999] 5800
currency string Да length: { size: 3 }, ISO 4217 (alfa-3) GBP
cvv string Нет minLength: { min: 3}, maxLength: { max: 4 }, only digits 911
first_name string Да minLength: { min: 1}, maxLength: { max: 32 } Card
last_name string Да minLength: { min: 1 }, maxLength: { max: 32 } Holder
card_holder string Да minLength: { min: 2 }, maxLength: { max: 32 } Card Holder
address string Нет minLength: { min: 2 } maxLength: { max: 32 } Billing address
city string Нет minLength: { min: 2 }, maxLength: { max: 32 } New Castle
state string Нет minLength: { min: 1 }, maxLength: { max: 32 } Texas
zip string Да minLength: { min: 2 }, maxLength: { max: 10 } 235467
country string Да minLength: { min: 2 }, maxLength: { max: 3 }, ISO 3166-1 alpha-3 GBR
user_phone string Нет minLength: { min: 7 }, maxLength: { max: 15 } 380111111111
user_email string Да minLength: { min: 6 }, maxLength: { max: 255 }, valid email 14848ff0308f8a396041ddde45de5f8a@gmail.com
user_ip string Да Ipv4Address 192.168.0.1
merchant_user_id string Нет maxLength: { max: 32 } 6d4a5d94821279725ecb3b0da9319d9b
merchant_domain_name string Нет maxLength: { max: 255 } vertu.com
merchant_affiliate_id string Нет maxLength: { max: 255 } 1234
merchant_product_name string Нет maxLength: { max: 255 } Chips
descriptor_merchant string Нет maxLength: { max: 255 } merchant.com
descriptor_phone string Нет maxLength: { max: 255 } 180012345678
token string Да length: { size: 36 } 14848ff0308f8a396041ddde45de5f8ffffa
callback_url string Да maxLength: { max: 255 } https://testshop.com/success
redirect_url string Да maxLength: { max: 255 } http://testshop.com/redirect

Пример ответа SALE3D (с токеном) в формате JSON:

{
    "api_version":1,
    "merchant_account":"your_merchant_account",
    "sessionid":"543e2136-d46c-4d7d-a3b3-075cf9adkl21",
    "transaction_unique_id":"sale3D_token001",
    "token":"5524fa52-75d8-4c7a-84ec-039d3097ab6g",
    "reference":" S3FF0000000039FDAEGH",
    "timestamp":1408001694,
    "authcode": "",
    "eci": 5,
    "acs_url": "https://callback-service.genome.eu/emitent/",
    "authcode":"",
    "status":"success",
    "code":0,
    "message":"transaction processed successfully"
}

Параметры ответа:

Имя параметра Тип Объязательное Правила Пример
api_version float Да maxLength: { max: 32 } 1
merchant_account string Да minLength: { min: 6 }, maxLength: { max: 32 } Testshop.com
sessionid string Да maxLength: { max: 36 } 53ec668b-c838-44b8-86f2-5c678ae9e3fc
transaction_unique_id string Да maxLength: { max: 32 }, minLength: { min: 1 } NwAkrkcPAmEcGzghnBwMeDRpXAPFsINg
token string Да length: { size: 36 } 14848ff0308f8a396041ddde45de5f8ffffa
reference string Да length: { size: 20 } ATFF1235432423
timestamp string Да unix timestamp 1408001694
authcode string Да maxLength: { max: 24 } 1111513
eci numeric Нет { 1, 2, 5, 6, 7 } 7
acs_url string Нет maxLength: { max: 255 } https://genome.eu:9443/PIT/ATS
status string Да { SUCCESS, DECLINE, ERROR } SUCCESS
code numeric Да Returns response code for the transaction Response codes table
message string Да Returns explanation of the response code Response codes table

После того, как транзакция SALE3D будет обработана, мерчант, в зависимости от требований бизнеса, может, но не обязан, осуществить следующие транзакции:

Транзакция REFUND

Пример REFUND запроса:

"Content-type: application/json" --data

{
    "api_version":1,
    "merchant_account":"your_merchant_account",
    "merchant_password":"account_password",
    "transaction_unique_id":"refund_request001",
    "transaction_type":"REFUND",
    "amount":10,
    "currency":"USD",
    "reference":"SLFF0000000039FDAEGG"
}

Назначение: используется для возврата средств на карту по списанной ранее транзакции.

Параметры запроса:

Имя параметра Тип Объязательное Правила Пример
api_version float Да maxLength: { max: 32 } 1
merchant_account string Да minLength: { min: 6 } maxLength: { max: 32 } Testshop.com
merchant_password string Да minLength: { min: 6 } maxLength: { max: 32 } testpassword
transaction_unique_id string Да minLength: { min: 1 } maxLength: { max: 32 } NwAkrkcPAmEcGzghnBwMeDRpXAPFsINg
transaction_type string Да validTransType, enum: { values: ["REFUND”]} REFUND
amount float Да float, maxLength: [0 - 9999999999.999] 5800
currency string Да length: { size: 3 }, ISO 4217 (alfa-3) GBP
reference string Да length: { size: 20 } SLFF0000000039FDAEGG референс SALE, SALE3D или SETTLE
merchant_user_id string Нет maxLength: { max: 32} 6d4a5d94821279725ecb3b0da9319d9b
descriptor_merchant string Нет maxLength: { max: 255 } merchant.com
descriptor_phone string Нет maxLength: { max: 255 } 180012345678

Пример ответа на запрос REFUND в формате JSON:

{
    "api_version":1,
    "merchant_account":"your_merchant_account",
    "sessionid":"543e2136-d46c-4d7d-a3b3-075cf9adkl21",
    "transaction_unique_id":"refund_request001",
    "token":"5524fa52-75d8-4c7a-84ec-039d3097ab6f",
    "reference":"RFF0000000039FDAEGG",
    "timestamp":1408001694,
    "authcode":"",
    "status":"success",
    "code":0,
    "message":"transaction processed successfully"
}

Параметры ответа:

Имя параметра Тип Объязательное Правила Пример
api_version float Да maxLength: { max: 32 } 1
merchant_account string Да minLength: { min: 6 } maxLength: { max: 32 } Testshop.com
sessionid string Да maxLength: { max: 36 } 53ec668b-c838-44b8-86f2-5c678ae9e3fc
transaction_unique_id string Да minLength: { min: 1 } maxLength: { max: 32 } NwAkrkcPAmEcGzghnBwMeDRpXAPFsINg
token string Да length: { size: 36 } 14848ff0308f8a396041ddde45de5f8ffffa
reference string Да length: { size: 20 } ATFF1235432423
timestamp string Да unix timestamp 1408001694
authсode string Да maxLength: { max: 24 } 1111513
status string Да { SUCCESS, DECLINE, ERROR } SUCCESS
code numeric Да Returns response code of the transaction Response codes table
message string Да Returns explanation of the response code Response codes table

После того, как транзакция REFUND была обработана, мерчант, в зависимости от требований бизнеса, может, но не обязан, осуществить следующие транзакции:

Транзакция VOID

Пример VOID запроса:

"Content-type: application/json" --data

{
    "api_version":1,
    "merchant_account":"your_merchant_account",
    "merchant_password":"account_password",
    "transaction_unique_id":"void_request001",
    "transaction_type":"VOID",
    "reference":"ATFF0000000039FDAEGG"
}

Назначение: используется для отмены транзакции до того, как она была списана.

Параметры запроса:

Имя параметра Тип Объязательное Правила Пример
api_version float Да maxLength: { max: 32 } 1
merchant_account string Да minLength: { min: 6 } maxLength: { max: 32 } Testshop.com
merchant_password string Да minLength: { min: 6 } maxLength: { max: 32 } testpassword
transaction_unique_id string Да minLength: { min: 1 } maxLength: { max: 32 } NwAkrkcPAmEcGzghnBwMeDRpXAPFsINg
transaction_type string Да validTransType, enum: { values: [”VOID”]} VOID
reference string Да length: { size: 20 } 14848ff0308f8a396041ddde45de5f8ffffa
merchant_user_id string Нет maxLength: { max: 32} 6d4a5d94821279725ecb3b0da9319d9b
descriptor_merchant string Нет maxLength: { max: 255 } merchant.com
descriptor_phone string Нет maxLength: { max: 255 } 180012345678

Пример ответа на VOID запрос в формате JSON:

{
    "api_version":1,
    "merchant_account":"your_merchant_account",
    "sessionid":"543e2136-d46c-4d7d-a3b3-075cf9adkl21",
    "transaction_unique_id":"void_request001",
    "token":"5524fa52-75d8-4c7a-84ec-039d3097ab6f",
    "reference":"VDFF0000000039FDAEGG",
    "timestamp":1408001694,
    "authcode":"",
    "status":"success",
    "code":0,
    "message":"transaction processed successfully"
}

Параметры ответа:

Имя параметра Тип Объязательное Правила Пример
api_version float Да maxLength: { max: 32 } 1
merchant_account string Да minLength: { min: 6 } maxLength: { max: 32 } Testshop.com
sessionid string Да maxLength: { max: 36 } 53ec668b-c838-44b8-86f2-5c678ae9e3fc
transaction_unique_id string Да minLength: { min: 1 } maxLength: { max: 32 } NwAkrkcPAmEcGzghnBwMeDRpXAPFsINg
token string Да length: { size: 36 } 14848ff0308f8a396041ddde45de5f8ffffa
reference string Да length: { size: 20 } ATFF1235432423
timestamp string Да unix timestamp 1408001694
authсode string Да maxLength: { max: 24 } 1111513
status string Да { SUCCESS, DECLINE, ERROR } SUCCESS
code numeric Да Returns response code of the transaction Response codes table
message string Да Returns explanation of the response code Response codes table

После того, как транзакция VOID была обработана, мерчант, в зависимости от требований бизнеса, может, но не обязан, осуществить следующие транзакции:

Транзакция CHECK

Пример CHECK запроса:

https://gateway.genome.eu/api/cc

"Content-type: application/json" --data

{
    "api_version":1,
    "merchant_account":"test_account ",
    "merchant_password":"test_passw",
    "transaction_type":"AUTH",
    "reference":"ATFF00000000395AD690",
     "transaction_unique_id":"myUniqId1"
}

Назначение: используется для проверки статуса транзакции. .

Параметры запроса:

Имя параметра Тип Объязательное Правила Пример
api_version float Да maxLength: { max: 32 } 1
merchant_account string Да minLength: { min: 6 } maxLength: { max: 32 } Testshop.com
merchant_password string Да minLength: { min: 6 } maxLength: { max: 32 } testpassword
transaction_type string Да validTransType, enum: { values: ["CHECK"]} CHECK
reference string Нет length: { size: 20 } 14848ff0308f8a396041ddde45de5f8ffffa
transaction_unique_id string Нет minLength: { min: 1 } maxLength: { max: 32 } NwAkrkcPAmEcGzghnBwMeDRpXAPFsINg

Параметры ответа в формате JSON:

{
    "api_version":1,
    "merchant_account":"test_account ",
    "sessionid":"5668fbfb-2d9c-492c-9f7c-11fb8ae9e3fc",
    "transactions":[
        {
            "reference":"ATFF00000000395AD690",
            "transaction_unique_id":"accept.1427710387.689199806",
            "transaction_type":"AUTH",
            "status":"SUCCESS",
            "code":0,
            "message":"SUCCESS",
            "token":"5519225d-3460-433f-ad4e-62649d0bb909",
            "timestamp":1429796980,
            "authcode":"111313"
        }
    ],
    "status":"success",
    "code":0,
    "message":"Transaction processed successfully"
}

Параметры ответа:

Имя параметра Тип Объязательное Правила Пример
api_version float Да maxLength: { max: 32 } 1
merchant_account string Да minLength: { min: 6 } maxLength: { max: 32 } Testshop.com
sessionid string Да maxLength: { max: 36 } 53ec668b-c838-44b8-86f2-5c678ae9e3fc
transactions array Да Should be array transactions
reference string Да length: { size: 20 }, transactions array element ATFF1235432423
transaction_unique_id string Да minLength: { min: 1 } maxLength: { max: 32 }, transactions array element NwAkrkcPAmEcGzghnBwMeDRpXAPFsINg
transaction_type string Да validTransType, array element AUTH
status string Да { SUCCESS, DECLINE, ERROR }, transactions array element success
code numeric Да Returns response code of the transaction, transactions array element Response codes table
message string Да Returns explanation of the response code, transactions array element Response codes table
token string Да length: { size: 36 }, transactions array element 14848ff0308f8a396041ddde45de5f8ffffa
timestamp string Да unix timestamp, transactions array element 1408001694
authcode string Да maxLength: { max: 24 }, transactions array element 1111513
status string Да { SUCCESS, DECLINE, ERROR } SUCCESS
code numeric Да Returns response code of the transaction Response codes table
message string Да Returns explanation of the response code Response codes table

После того, как транзакция CHECK была обработана, мерчант может осуществлять любые транзакции.

Транзакция Tokenize

Пример TOKENIZE запроса:

https://gateway.genome.eu/api/cc

"Content-type: application/json" --data

{
    "api_version":1,
    "merchant_account":"test_account ",
    "merchant_password":"test_passw",
    "transaction_type":"TOKENIZE",
    "card_number":"4111111111111111",
    "card_exp_month":"05",
    "card_exp_year":"2016",
    "cvv":"111",
    "card_holder":"John Doe"
}

Назначение: используется для токенизации номера карты при помощи генерации случайного набора параметров и символов.

Параметры запроса:

Имя параметра Тип Объязательное Правила Пример
api_version float Да maxLength: { max: 32 } 1
merchant_account string Да minLength: { min: 6 } maxLength: { max: 32 } Testshop.com
merchant_password string Да minLength: { min: 6 } maxLength: { max: 32 } testpassword
transaction_type string Да validTransType, enum: { values: [”TOKENIZE”]} TOKENIZE
card_number string Да minLength: { min: 13 }, maxLength: { max: 19 } only digits, Luhn algorithm 4864369454425300
card_exp_month string Да length: { size: 2 }, only digits 05
card_exp_year string Да length: { size: 4 }, only digits 2016
card_holder string Да minLength: { min: 3 } maxLength: { max: 32 } Card Holder

Пример ответа в формате JSON:

{
    "api_version":1,
    "merchant_account":"test_account ",
    "sessionid":"5538fcc8-8070-4e62-9a67-773f8ae9e3fc",
    "transaction_unique_id":null,
    "token":"54a9429f-00e0-475f-bc8f-22a158a0e038",
    "reference":null,
    "timestamp":1429798090,
    "authcode":null,
    "status":"success",
    "code":0,
    "message":"Transaction processed successfully"
}

Параметры ответа:

Имя параметра Тип Объязательное Правила Пример
api_version float Да maxLength: { max: 32 } 1
merchant_account string Да minLength: { min: 6 } maxLength: { max: 32 } Testshop.com
sessionid string Да maxLength: { max: 36 } 53ec668b-c838-44b8-86f2-5c678ae9e3fc
authcode string Да maxLength: { max: 24 } null
token string Да length: { size: 36 } 14848ff0308f8a396041ddde45de5f8ffffa
reference string Да length: { size: 20 } null
transaction_unique_id string Да minLength: { min: 1 } maxLength: { max: 32 } null
timestamp string Да unix timestamp 1408001694
status string Да { SUCCESS, DECLINE, ERROR } SUCCESS
code numeric Да Returns response code of the transaction Response codes table
message string Да Returns explanation of the response code Response codes table

После осуществления транзакции Tokenize, мерчант может использовать Токен карты вместо реальных данных кредитной карты.

Erroneous ответ

Назначение: данный тип ответа будет передан в случае получения некорректного (кроме CHECK) запроса или в случае некорретной работы системы. Все обязаетельные поля будут переданы в ответе.

Параметры запроса:

Имя параметра Тип Объязательное Правила Пример
api_version float Да maxLength: { max: 32 } 1
merchant_account string Да minLength: { min: 6 } maxLength: { max: 32 } Testshop.com
sessionid string Да maxLength: { max: 36 } 53ec668b-c838-44b8-86f2-5c678ae9e3fc
transaction_unique_id string Да null null
token string Да length: { size: 36 } null
reference string Да length: { size: 20 } null
authcode string Да maxLength: { max: 24 } null
eci numeric Нет { 1, 2, 5, 6, 7 } null
pareq string Нет maxLength: { max: 65535 } null
acs_url string Нет maxLength: { max: 255 } null
timestamp string Да unix timestamp 1408001694
status string Да {ERROR } ERROR
code numeric Да Returns response code of the transaction Response codes table
message string Да Returns explanation of the response code Response codes table

Проверка ошибочного запроса

Назначение: данный тип запроса будет осуществлен в случае получения некорректного запроса CHECK или в случае некорретной работы системы. Все обязательные поля будут переданы в ответе.

Параметры запроса:

Имя параметра Тип Объязательное Правила Пример
api_version float Да maxLength: { max: 32 } 1
merchant_account string Да minLength: { min: 6 }, maxLength: { max: 32 } null
sessionid string Да maxLength: { max: 36 } null
reference string Да length: { size: 20 } null
transaction_unique_id string Да minLength: { min: 1 } maxLength: { max: 32 } null
token string Да length: { size: 36 } null
authcode string Да maxLength: { max: 24 } null
timestamp string Да unix timestamp 1429797960
status string Да { ERROR } ERROR
code numeric Да Returns response code of the transaction Response codes table
message string Да Returns explanation of the response code Returns explanation of the response code

API по выплатам

Обзор

API по выплатам предназначено для выплат денежных средств клиентам на карты или электронные кошельки.

Web сервис URL
Live Genome Payout API Service https://gateway.genome.eu/api/payout
Test Genome Payout API Service https://gateway-sandbox.genome.eu/api/payout

Поиск метода

Пример запроса для поиска возможного способа выплаты:

"Content-type: JSON, POST" --data

{
    "api_version": 1,
    "method": "list",
    "merchant_account": "my_merchant_account",
    "merchant_password": "my_merchant_password"
}

Параметры запроса:

Поле Объязательное Тип Описание
api_version Да int API версия.
method Да string List метод - возвращает способы выплаты в ответе.
merchant_account Да string Аккаунт мерчанта.
merchant_password Да string Пароль от аккаунта мерчанта.

Пример ответа в формате JSON:

    {
    "sessionid": "someid",
    "status": "success",
    "code": 0,
    "message": "Request processed successfully",
    "methods": [
        {
            "type": "card",
            "mid_name": "my_mid_name",
            "mid_reference": "0001234567J",
            "currencies": ["USD"]
        },
        {
            "type": "qiwi",
            "mid_name": "my_mid_name",
            "mid_reference": "0001234567J",
            "currencies": ["EUR", "USD"]
        }
    ]
}

Параметры ответа:

Поле Объязательное Тип Описание
sessionid Да string Id сессии
timestamp Да string Время отправки запроса
methods Да *method[] Доступные методы для выплаты.
status Да string ENUM ['success', 'decline', 'error'] Статус ответа
code Да int Код ответа
message Да string Описание ответа

Методы

Поле Объязательное Тип Описание
type Да string Тип метода
mid_name Да string Имя МИДа
mid_reference Да string Референс МИДа
currencies Да string[] Поддерживаемые валюты

Примечание для init метода:

В случае успешного запроса на выплату мерчант получит ответ со status:pending и code:0. Финальный статус по выплате мерчант получает в коллбэке.

Выплата на карту

Пример запроса выплаты на карту:

"Content-type: JSON, POST" --data

{
    "api_version": 1,
    "method": "init",
    "merchant_account": "my_merchant_account",
    "merchant_password": "my_merchant_password",
    "transaction_unique_id": "0001234567",
    "amount": 10,
    "currency": "USD",
    "callback_url": "https://mycallback.com/",
    "user_id": "someId",
    "user_ip": "127.0.0.1",
    "user_email": "user_email@example.com",
    "card": {
        "card_cvv": "022",
        "card_number": "xxx",
        "card_holder": "John Doe",
        "card_exp_year": "2020",
        "card_exp_month": "12"
    }
}

Параметры запроса по выплате на карту:

Поле Объязательное Тип Описание
api_version Да int API версия
method Да string Init метод
merchant_account Да string Аккаунт мерчанта
merchant_password Да string Пароль от аккаунта мерчанта
transaction_unique_id Да string Уникальный Id транзакции
mid_reference Нет string МИД референс
amount Да float\int Сумма выплаты
currency Да string Валюта выплаты. Пример: USD, EUR, GBP.
callback_url Да string Коллбек урла с https протоколом.
user_id Да string Уникальный Id пользователя в мерчант системе.
user_email Да string Email пользователя
user_ip Да string IP адрес пользователя
user_first_name Нет string Имя пользователя
user_last_name Нет string Фамилия пользователя
user_phone Нет string Номер телефона пользователя
user_state Нет string Штат/ область пользователя
user_country Нет string Страна пользователя
user_city Нет string Город пользователя
user_address Нет string Адрес пользователя
user_zip Нет string Почтовый индекс пользователя
user_date_of_birth Нет string Дата рождения, формат - ГГГГММДД
card[card_number] Да luhn string Номер карты
card[card_cvv] Нет numeric[3,4] CVV код карты пользователя. Состоит из 3 или 4 цифр
card[card_holder] Нет string Имя держателя карты
card[card_exp_year] Нет numeric[4] Год истечения срока платежной карты, состоит из 4 цифр
card[card_exp_month] Нет numeric[2] Месяц истечения срока платежной карты, состоит из 2 цифр

Примечание: в зависимости от экваера набор полей может изменяться.

Альтернативные методы выплаты

Пример для выплаты на QIWI кошелек:

"Content-type: JSON, POST" --data


{
  "api_version": 1,
  "method": "init",
  "merchant_account": "my_merchant_account",
  "merchant_password": "my_account_password",
  "transaction_unique_id": "transaction_unique_id",
  "mid_reference": "MD0000000D36A5F9",
  "amount": 10,
  "currency": "RUB",
  "callback_url": "callback_url",
  "user_id": "user_id",
  "user_ip": "user_ip",
  "user_email": "user_email",
  "qiwi": {
    "wallet_id": "qiwi wallet number"
  }
}

Параметры для выплаты на QIWI кошелек:

Параметр Объязательное Тип Описание
api_version Да int API версия
method Да string Init метод
merchant_account Да string Название аккаунта
merchant_password Да string Пароль для аккаунта
transaction_unique_id Да string Уникальный Id транзакции
mid_reference Нет string Мид референс
amount Да float\int Сумма выплаты
currency Да string Валюта в ISO формате. Примеры: USD, EUR, GBP.
callback_url Да string Урла для callback ответа. Должна иметь SSL сертификат.
user_id Да string Уникальный Id пользователя в системе мерчанта.
user_email Да string Email пользователя
user_ip Да string IP адрес пользователя
user_first_name Нет string Имя
user_last_name Нет string Фамилия
user_phone Нет string Номер телефона
user_state Нет string Область/штат
user_country Нет string Страна
user_city Нет string Город
user_address Нет string Адрес
user_zip Нет string Почтовый индекс
qiwi['wallet_id'] Да numeric[9,15] Id кошелька

Пример ответа в JSON формате:

{
    "sessionid": "5118fcfc-2d9c-492c-9f7c-21470c",
    "status": "success",
    "code": 0,
    "message": "Request processed successfully"
}

Параметры ответа:

Параметр Объязательное Тип Описание
sessionid Да string Id сессии.
status Да string ENUM ['success', 'decline', 'error'] Статус транзакции
code Да int Код ответа
message Да string Описание

Пример выплаты на Yandex кошелек:

"Content-type: JSON, POST" --data


{
  "api_version": 1,
  "method": "init",
  "merchant_account": "my_merchant_account",
  "merchant_password": "my_account_password",
  "transaction_unique_id": "transaction_unique_id",
  "mid_reference": "MD0000000D37A6C9",
  "amount": 10,
  "currency": "RUB",
  "callback_url": "callback_url",
  "user_id": "user_id",
  "user_ip": "user_ip",
  "user_email": "user_email",
  "yandex": {
    "wallet_id": "yandex wallet number"
  }
}

Параметры для выплаты на Yandex кошелек:

Параметр Объязательное Тип Описание
api_version Да int API версия
method Да string Init метод
merchant_account Да string Название аккаунта
merchant_password Да string Пароль для аккаунта
transaction_unique_id Да string Уникальный Id транзакции
mid_reference Нет string Мид референс
amount Да float\int Сумма выплаты
currency Да string Валюта в ISO формате. Примеры: USD, EUR, GBP.
callback_url Да string Урла для callback ответа. Должна иметь SSL сертификат.
user_id Да string Уникальный Id пользователя в системе мерчанта.
user_email Да string Email пользователя
user_ip Да string IP адрес пользователя
user_first_name Нет string Имя
user_last_name Нет string Фамилия
user_phone Нет string Номер телефона
user_state Нет string Область/штат
user_country Нет string Страна
user_city Нет string Город
user_address Нет string Адрес
user_zip Нет string Почтовый индекс
yandex['wallet_id'] Да numeric[9,15] Id яндекс кошелька

Пример ответа в JSON формате:

{
    "sessionid": "5118fcfc-2d9c-492c-9f7c-214341",
    "status": "success",
    "code": 0,
    "message": "Request processed successfully"
}

Параметры ответа:

Параметр Объязательное Тип Описание
sessionid Да string Id сессии.
status Да string ENUM ['success', 'decline', 'error'] Статус транзакции
code Да int Код ответа
message Да string Описание

Выплата на карту по Токену

Пример выплаты по Токену:

"Content-type: JSON, POST" --data

{
    "api_version": 1,
    "method": "init",
    "merchant_account": "my_merchant_account",
    "merchant_password": "my_merchant_password",
    "transaction_unique_id": "0001234567",
    "amount": 10,
    "currency": "USD",
    "callback_url": "https://mycallback.com/",
    "user_id": "someId",
    "user_ip": "127.0.0.1",
    "user_email": "user_email@example.com",
    "card": {
        "token": "token_value",
        "card_holder": "John Doe"
    }
}

Параметры запроса для выплаты на карту по Токену:

Поле Объязательное Тип Описание
api_version Да int API версия
method Да string Init метод
merchant_account Да string Аккаунт мерчанта
merchant_password Да string Пароль от аккаунта мерчанта
transaction_unique_id Да string Уникальный Id транзакции
mid_reference Нет string МИД референс
amount Да float\int Сумма выплаты
currency Да string Валюта выплаты. Пример: USD, EUR, GBP.
callback_url Да string Коллбек урла с https протоколом.
user_id Да string Уникальный Id пользователя в мерчант системе.
user_email Да string Email пользователя
user_ip Да string IP адрес пользователя
user_first_name Нет string Имя пользователя
user_last_name Нет string Фамилия пользователя
user_phone Нет string Номер телефона пользователя
user_state Нет string Штат/ область пользователя
user_country Нет string Страна пользователя
user_city Нет string Город пользователя
user_address Нет string Адрес пользователя
user_zip Нет string Почтовый индекс пользователя
card[token] Да string Значение токена
card[card_holder] Нет string Имя держателя карты

Пример ответа в формате JSON:

{
    "sessionid": "5118fcfc-2d9c-492c-9f7c-21470a",
    "status": "success",
    "code": 0,
    "message": "Request processed successfully"
}

Параметры ответа:

Поле Объязательное Тип Описание
sessionid Да string уникальный Id сессии
status Да string ENUM ['success', 'decline', 'error'] Статус ответа
code Да int Код ответа
message Да string Описание ответа

Отмена выплаты

Пример запроса об отмене выплаты:

"Content-type: JSON, POST" --data

{
    "api_version": 1,
    "method": "cancel",
    "merchant_account": "my_merchant_account",
    "merchant_password": "my_merchant_password",
    "transaction_unique_id": "trx000003"
}

Параметры запроса по отмене выплаты:

Поле Объязательное Тип Описание
api_version Да int API версия.
method Да string Cancel метод при отмене выплаты.
merchant_account Да string Аккаунт мерчанта
merchant_password Да string Пароль от аккаунта мерчанта
transaction_unique_id Да string Уникальный Id транзакции

Пример ответа в формате JSON:

{
    "code": 0,
    "reference": "VDFF000000000001",
    "sessionid": "5118fcfc-2d9c-492c-9f7c-77701d",
    "status": "success",
    "message": "Transaction has been voided"
}

Параметры ответа:

Поле Объязательное Тип Описание
code Да int Код ответа
reference Да string Void референс транзакции
sessionid Да string Уникальный Id сессии
status Да string ENUM ['success', 'decline', 'error'] Статус ответа
message Да string Описание ответа

Callback

Пример callback ответа в формате JSON:

{
    "token": "58a3357e-4cc0-4a4d-977f-1156431a4c99",
    "reference": "PTFF000000000001",
  "transaction_unique_id": "20170114-02",
    "status": "success",
    "code": 0,
    "message": "Transaction processed successfully!"
}

Параметры callback ответа:

Поле Объязательное Тип Описание
token Да string Значение токена
reference Да string Уникальный референс транзакции
transaction__unique_id Да string Статус транзакции
status Да string ENUM ['success', 'decline', 'error'] Статус ответа
code Да int Код ответа
message Да string Описание ответа

Статусы транзакций

Статусы транзакций по выплатам:

Статус Описание
NEW Создана транзакция по выплате
SUCCESS Транзакция прошла успешно
ERROR Ошибка по транзакции
DECLINED Транзакция отклонена
CANCELED Транзакция отменена
VALIDATION Транзакция проходит валидацию
PROCESSING Транзакция обрабатывается
PENDING PROCESSING Транзакция находится в очереди
PENDING POSTBACK Ответ ожидается
PROCESSING POSTBACK Обработка ответа

Коды ответов

Коды ответов транзакций по выплатам:

Module Code Value Message (can be extended depending on case)
Payout 3300 GENERAL DECLINE General payout error
3310 VALIDATION DECLINE Payout validation error
3311 INVALID MID REFERENCE Invalid mid reference
3330 UNREGISTERED CARD Unregistered card
FRS 4000 GENERAL RECONCILLIATION ERROR general reconcilliation error
4001 RECONCILLIATION INCOMPLETE reconcilliation incomplete
4002 RECONCILLIATION AMOUNT MISMATCH reconcilliation amount mismatch
4003 RECONCILLIATION COUNT MISMATCH reconcilliation count mismatch
4004 GENERAL FRS ERROR FRS general error
4005 BALANCE_IS_NOT_AVAILABLE Balance is not available
4006 CURRENCY_IS_NOT_AVAILABLE Currency is not available/td>
4007 EXCEEDED_AMOUNT Exceeded amount

Запрос по требованию

При помощи запроса по требованию (QOD API Genome) вы сможете получить всю историю транзакций, которые вы осуществили.

Доступ к Genome Qod API

Запрос Genome на тест и лайв по требованию API может быть осуществлен с использованием следующих адресов:

Web Сервис URL
Live QOD Service https://gateway.genome.eu/qod
Test QOD Service https://gateway-sandbox.genome.eu/qod

Рабочий процесс Qod

Мерчант запрашивает данные транзакций для своего аккаунта через QOD Service API используя методы, описанные ниже. QOD Service API генерирует отчеты для каждого запроса в соответствии с типом запроса и типом транзакционного отчета.

Форматы запросов Qod

Форматы ответов Qod

Пример QOD запроса:

https://gateway.genome.eu/qod/

 {
"api_version" : "1.0",
"merchant_account" : "TestQOD",
"merchant_password" : "helloworld",
"time_from" : "1408001644",
"time_to" : "1408001645",
"qod_type" :"transactions",
"order" :"asc",
"page" :"1",
"limit" :"50" 
}

Данная информация должна запрашиваться страница за страницей, разделенных по 1000 записей на странице. Возможно сделать запрос к любой странице по ее номеру.

**Параметры запросов универсальны для всех типов запросов

Имя параметра Тип Обязательное Правила Описание
api_version float\string yes maxLength: { max: 32 } Версия QOD API
merchant_account string yes maxLength: { max: 32 } Имя аккаунта QOD account
merchant_password string yes minLength: { min: 6 }, maxLength: { max: 32 } Пароль аккаунта QOD account
time_from string yes timestamp Обработка транзакций время от времени, метка времени
time_to string yes timestamp Обработка транзакций время от времени, метка времени
qod_type string yes enum: {values: ["transactions”, ”chargebacks”, “modifications”]} Типы транзакций используются в запросе: transactions \ chargebacks \ modifications
order string no1 enum: {values: ["acs”, ”desc”]} Заказ ASC (по умолчанию )/DESC
page string no2 minLength: { min: 1 } maxLength: { max: 12 } Фетчинг номера страницы. Если ответ содержит количество транзакций выше предельного значения, фетчинг возможна. Страница содержит ограниченное число записей (Limit).
limit string no3 minLength: { min: 1 } maxLength: { max: 1000 } Количество фетчинговых транзакций 1000 по умолчанию. Количество не может быть больше 1000

Примечание 1: Если заказ не определен, используется порядок ASC
Примечание 2: Если страница не определена, только транзакции 1-ой страницы должны быть выбраны в соответствии с установленным лимитом
Примечание 3: Если предел не определен, должны быть осуществлены 1000 транзакций.

Транзакции

Пример запроса в формате JSON:

{
  "api_version": "1.0",
  "transactions": [
    {
      "transaction_type": "AUTH",
      "status": "SUCCESS",
      "mode": "CC",
      "reference": "ATFF00000000395376F6",
      "base_reference": null,
      "amount": 10,
      "currency": "GBP",
      "merchant": {
        "merchant_account": "TestQOD",
        "descriptor_merchant": "",
        "descriptor_phone": "",
        "merchant_domain_name": "",
        "merchant_product_name": "",
        "merchant_affiliate_id": ""
      },
      "user": {
        "first_name": "User",
        "last_name": "Test",
        "country": "GBR",
        "state": "xxx",
        "city": "London",
        "address": "123 Streetname",
        "zip": "11111",
        "user_ip": "1.1.1.1",
        "user_email": "testemail@testdomain.net",
        "user_phone": "+123456789012"
      },
      "card": {
        "card_holder": "Test Cardholder",
        "brand": "VISA",
        "bin": "400002",
        "last": "1234",
        "exp_month":"06",
       "exp_year":"2015"
      },
      "bank": {
        "id": 1,
        "authcode": "111737",
        "time": 1432542316.3496
      },
      "time": 1420447215.4163,
      "token": "54817d79-8b5c-4c6f-a266-7f2264ed02ad",
      "transaction_unique_id": "accept.1420447212.1505680771",
      "pares": "",
      "code": 0,
      "message": "SUCCESS"
    }
  ],
  "merchant_account": "TestQOD",
  "timestamp": 1432542316.3496,
  "status": "success",
  "code": 0,
  "message": "Transaction processed successfully"
}

Назанчение: Используя запрос транзакций qod_type, можно получить все транзакции, осуществленные на аккаунте мерчанта.

Параметры ответа:

Имя параметра Тип Обязательное Правила Описание
api_version float\string yes maxLength: { max: 32 } Версия QOD API
merchant_account string yes maxLength: { max: 32 } Имя аккаунта QOD
timestamp string yes unix timestamp Время ответа QOD
status string yes maxLength: { max: 10 } Успешный QOD ответ должен содержать статус success
code string yes length: { size: 4 } Код ответа QOD
message string no maxLength: { max: 255 } Определение кода ответа QOD
transactions array yes Should be array Содержит данные транзакции в массиве
transaction_type string yes enum('SALE', 'AUTH', 'AUTH3D', 'SALE3D', 'SETTLE', 'REFUND', 'VOID'), array element Тип транзакции
status string yes enum('SUCCESS', 'DECLINED', 'ERROR', 'MALFORMED', 'PROCESSING', 'BATCHED', 'FRAUDED', 'CHARGEDBACK', 'REFUNDED', 'VOIDED', 'PARTIAL-REFUNDED', 'WRONGREF') , array element Статус транзакции
mode string yes enum('CC', 'TOKEN', 'REF', 'CASCADE') , array element Режим транзакции
reference string yes length: { size: 20 }, array element Ссылка транзакции Genome
base_reference string\null yes length: { size: 20 }, array element Базовая ссылка транзакции, если существует
amount float yes decimal(14,4) unsigned, array element Сумма транзакции
currency string yes length: { size: 3 }, ISO 4217 (alfa-3) , array element Валюта транзакции
time float\null yes unix timestamp, array element Время транзакции Genome
token string yes length: { size: 36 }, array element Токен транзакции
transaction_unique_id string yes maxLength: { max: 32 }, array element Уникальный идентификатор транзакции со стороны мерчанта
pares string yes maxLength: { max: 65535 }, array element Транзакции PaRes для 3DS PaRes
code numeric\null yes length: { size: 4 }, array element Код ответа транзакции, таблица кода ответов ниже
message string\null yes maxLength: { max: 255 }, array element Код ответа транзакции, таблица кода ответов ниже
merchant array\null yes Should be array Содержит данные транзакции мерчанта
merchant_account string yes maxLength: { max: 64 }, array element Аккаунт мерчанта используется для генерации транзакции
descriptor_merchant string yes maxLength: { max: 255 }, array element Дескриптор мерчанта
descriptor_phone string yes maxLength: { max: 255 }, array element Дескриптор телефона мерчанта
merchant_domain_name string yes maxLength: { max: 255 }, array element Название вебсайта мерчанта
merchant_product_name string yes maxLength: { max: 255 }, array element Название продукта мерчанта
merchant_affiliate_id string yes maxLength: { max: 255 }, array element Название идентификатора афилейнта мерчанта
user array\null yes Should be array Содержит данные транзакции покупателя
first_name string yes maxLength: { max: 255 }, array element Имя покупателя
last_name string yes maxLength: { max: 255 }, array element Фамилия покупателя
country string yes maxLength: { max: 255 }, array element Страна покупателя
state string yes maxLength: { max: 255 }, array element Область / Штат покупателя
city string yes maxLength: { max: 255 }, array element Город покупателя
address string yes maxLength: { max: 255 }, array element Адрес покупателя
zip string yes maxLength: { max: 255 }, array element Индекс покупателя
user_ip string yes maxLength: { max: 255 }, array element IP адрес покупателя
user_email string yes maxLength: { max: 255 }, array element email адрес покупателя
user_phone string yes maxLength: { max: 255 }, array element Номер телефона покупателя
card array\null yes Should be array *Содержит данные карты транзакции *
card_holder string yes maxLength: { max: 100 }, array element Имя держателя карты
brand string yes maxLength: { max: 255 }, array element Бренд карты
bin string yes length: { size: 6 }, array element Данные карты BIN – первые 6 цифр
last string yes length: { size: 4 }, array element Данные номера карты – последние 4 цифры
exp_month string yes length: { size: 2 }, array element Месяц истечения годности карты
exp_year string yes length: { size: 4 }, array element Год истечения годности карты
bank array\null yes Should be array Содержит данные транзакции банка
id int yes maxLength: { max: 20 }, array element Идентификационный код банка
authcode string yes maxLength: { max: 45 }, array element Код авторизации банка
time float\null yes unix timestamp, array element Время транзакции банка

Чарджбэки

Параметры ответа в формате JSON:

{
  "api_version": "1.0",
  "chargebacks": [
    {
      "transaction": {
        "transaction_type": "SETTLE",
        "status": "CHARGEDBACK",
        "mode": "REF",
        "reference": "STFF0000000039546C12",
        "base_reference": "ATFF0000000039546BBF",
        "amount": 10,
        "currency": "GBP",
        "merchant": {
          "merchant_account": "TestQOD",
          "descriptor_merchant": "",
          "descriptor_phone": "",
          "merchant_domain_name": "",
          "merchant_product_name": "",
          "merchant_affiliate_id": ""
        },
        "user": {
          "first_name": "User",
          "last_name": "Test",
  "country": "GBR",
          "state": "xxx",
          "city": "London",
          "address": "123 Streetname",
          "zip": "11111",
          "user_ip": "",
          "user_email": "testemail@testdomain.net",
          "user_phone": "+123456789012"
        },
        "card": {
          "card_holder": "Test Cardholder7",
          "brand": "VISA",
          "bin": "400002",
          "last": "1234",
          "exp_month":"06",
         "exp_year":"2015"
        },
        "bank": {
          "id": 1,
          "authcode": "111575",
          "time": null
        },
        "time": 1421938805.751,
        "token": "",
        "transaction_unique_id": "accept.1421938801.604138208",
        "pares": "",
        "code": 0,
        "message": "SUCCESS"
      },
      "chargeback": {
        "status": "OPENED",
        "type": "CHARGEBACK_REVERSAL",
        "reason": "3102",
        "description": "Lost/Stolen card",
        "transaction_type": "CHARGEBACK",
        "transaction_status": "SUCCESS",
        "mode": "REF",
        "reference": "CBFF000000003958A4B1",
        "base_reference": "STFF0000000039546C12",
        "amount": 10,
        "bank": {
          "id": 1,
          "authcode": "",
          "time": 1428576548.6336,
          "update_time": 1428576548.6336
        },
        "time": 1428576550.499
      }
    }
  ],
  "merchant_account": "TestQOD",
  "timestamp": 1432540436.4364,
  "status": "success",
  "code": 0,
  "message": "Transaction processed successfully"
}

Назначение: Использование запроса чарджбэков qod_type позволяет получить все чарджбэки по аккаунту мерчанта.

Параметры ответа:

Имя параметра Тип Обязательное Правила Описание
api_version float Yes maxLength: { max: 32 } QOD API версия
merchant_account string Yes maxLength: { max: 32 } Наименование аккаунта QOD
timestamp string Yes unix timestamp Время ответа QOD
status string Yes maxLength: { max: 10 } Успешный QOD ответ должен содержать статус Success
code string Yes length: { size: 4 } QOD код ответа
message string No maxLength: { max: 255 } QOD описание кода ответа
chargebacks array Yes Should be array Содержит данные транзакции возвратного платежа (инициированного и возвращенного) в массивах
transaction array\null Yes Should be array Массив содержит данные транзакции для возвращенной транзакции. Используется та же структура, как и в транзакциях qod_type
chargeback array\null Yes Should be array Содержит данные возвращенной транзакции
status string Yes maxLength: { max: 255 }, array element Статус возвратного платежа
type string Yes maxLength: { max: 255 }, array element Тип возвратного платежа
reason string Yes maxLength: { max: 255 }, array element Причина возвратного платежа
description string Yes maxLength: { max: 255 }, array element Описание возвратного платежа
transaction_type string Yes enum('CHARGEBACK'), array element Тип возвратного платежа
transaction_status string Yes enum('SUCCESS'), array element Статус возвратного платежа
mode string Yes enum( 'REF'), array element Режим возвратного платежа
reference string Yes length: { size: 20 }, array element Ссылка Genome возвратного платежа
base_reference string\null Yes length: { size: 20 }, array element Базовая ссылка Genome возвратного платежа
amount float Yes decimal(14,4) unsigned, array element Сумма возвратного платежа
time float\null Yes unix timestamp, array element Genome время возвратного платежа
bank array\null Yes Should be array Содержит данные транзакции банка
id int Yes maxLength: { max: 20 }, array element Идентификатор банка
authcode string Yes maxLength: { max: 45 }, array element Код авторизации банка
time float\null Yes unix timestamp, array element Время транзакции банка
update_time float\null Yes unix timestamp, array element Обновленное время транзакции банка

Модификации

Пример в формате JSON:

{
  "api_version": "1.0",
  "modifications": [
    {
      "transaction": {
        "transaction_type": "AUTH",
        "status": "SUCCESS",
        "mode": "CASCADE",
        "reference": "ATFF0000000039545997",
        "base_reference": null,
        "amount": 10,
        "currency": "GBP",
        "merchant": {
          "merchant_account": "TestQOD",
          "descriptor_merchant": "",
          "descriptor_phone": "",
          "merchant_domain_name": "",
          "merchant_product_name": "",
          "merchant_affiliate_id": ""
        },
        "user": {
          "first_name": "User",
          "last_name": "Test",
          "country": "GBR",
          "state": "xxx",
          "city": "London",
          "address": "123 Streetname",
          "zip": "11111",
          "user_ip": "1.1.1.1",
          "user_email": "testemail@testdomain.net",
          "user_phone": "+123456789012"
        },
        "card": {
          "card_holder": "Test Cardholder2",
          "brand": "VISA",
          "bin": "400002",
          "last": "1234",
          "exp_month":"06",
          "exp_yeat":"2015"
        },
        "bank": {
          "id": 356,
          "authcode": "authCode_1421931998.6174",
          "time": 1432544175.6856
        },
        "time": 1421931997.4228,
        "token": "54c0f42b-33ac-4cd7-a9dc-0ac4d0d54c0f",
        "transaction_unique_id": "accept.1421931994.715872787",
        "pares": "",
        "code": 0,
        "message": "SUCCESS"
      },
      "modification": {
        "reason": "",
        "description": "",
        "transaction_type": "VOID",
        "transaction_status": "SUCCESS",
        "mode": "MODIFICATION",
        "reference": "VDFF0000000039548C7E",
        "base_reference": "ATFF0000000039545997",
        "amount": 10,
        "bank": {
          "id": 1,
          "authcode": "",
          "time": 1432544175.6856
        },
        "time": 1422280865.0313,
    "update_time": 1422280865.0313,
        "code": 3100,
        "message": "Decline"
      }
    }
  ],
  "merchant_account": "TestQOD",
  "timestamp": 1432544175.6856,
  "status": "success",
  "code": 0,
  "message": "Transaction processed successfully"
}

Назначение: Использование запроса Modifications qod_type позволяет получить все модифицированные транзакции по аккаунту мерчанта.

Параметры ответа:

Имя параметра Тип Обязательное Правила Описание
api_version float yes maxLength: { max: 32 } QOD API версия
merchant_account string yes maxLength: { max: 32 } Аккаунт мерчанта
timestamp string yes unix timestamp Время ответа QOD
status string yes maxLength: { max: 10 } Успешный ответ QOD должен содержать успешный статус
code string yes length: { size: 4 } код ответа QOD
message string no maxLength: { max: 255 } QOD описание кода ответа
modifications array yes Should be array Содержит измененные данные транзакции (исходые и измененные) в массивах
transaction array\null yes Should be array Массив содержит исходные данные транзакции для измененной транзакции. Используется такая же структура транзакции qod_type
modification array\null yes Should be array Содержит транзакцию измененные данные в массиве
reason string maxLength: { max: 255 }, array element Причина изменений
description string maxLength: { max: 255 }, array element Описание изменений
transaction_type string yes validTransType, array element Тип изменений транзакции
transaction_status string yes enum('SUCCESS', 'DECLINED', 'ERROR', 'MALFORMED', 'PROCESSING', 'BATCHED', 'FRAUDED', 'CHARGEDBACK', 'REFUNDED', 'VOIDED', 'PARTIAL-REFUNDED', 'WRONGREF'), array element Статус измененной транзакции
mode string yes enum('MODIFICATION'), array element Режим измененной транзакции
reference string yes length: { size: 20 }, array element Genome ссылка изменной транзакции
base_reference string\null yes length: { size: 20 }, array element Genome основная ссылка изменной транзакции
amount float yes decimal(14,4) unsigned, array element Сумма изменной транзакции
time float yes unix timestamp, array element Изменное время транзакции
update_time float yes unix timestamp, array element Обновленное измененное время транзакции
code numeric\null yes length: { size: 4 }, array element Код ответа измененной транзакции, коды ответов в таблице ниже
message string\null yes maxLength: { max: 255 }, array element Код ответа измененной транзакции, коды ответов в таблице ниже
bank array\null yes Should be array Содержит банковские данные транзакции
id int yes maxLength: { max: 20 }, array element Идентификатор банка
authcode string yes maxLength: { max: 45 }, array element Авторизационный код банка
time float yes unix timestamp, array element Время транзакции банка

Коды ответов на запрос проверки (не API)

Код сообщение (может быть длиннее в некоторых случаях)
400 НЕВОЗМОЖНО СЧИТАТЬ ДАННЫЕ ВХОДЯЩЕГО ЗАПРОСА

Пустой ответ

Назначение: Пустой ответ (Empty Response) - данные настройки должны быть отображены в случае получения ответа, не содержащего никаких данных (пустого).

Параметр ответа:

Имя параметра Тип Обязательное Правила Описание
api_version float yes maxLength: { max: 32 } QOD API версия
merchant_account string yes minLength: { min: 6 }, maxLength: { max: 32 } Аккаунт мерчанта
timestamp string yes unix timestamp Timestamp ответа
transactions \ chargebacks \ modifications array\null yes enum: { values: ["transactions”, ”chargebacks”, “modifications”]} qod тип может быть использован для запросов transactions \ chargebacks \ modifications
status string yes maxLength: { max: 10 } Успешный ответ должен содержать в себе успешный статус
code string yes Length: {4 } Код ответа QOD
message string no maxLength: { max: 255 } Сообщение ответа QOD

Ошибочный ответ

Пример в формате JSON:

{
  "api_version":"1.0",
  "transactions":[],
  "merchant_account":"TestQOD",
  "timestamp":1432216783.6329,
  "status":"error",
  "code":5008,
  "message":"Time from cannot be greater than Time to"
}

Назначение: Ошибочный ответ (Erroneous response) - данные поля должны быть переданы в случае ошибочного ответа или данных.

Параметры ответа:

Имя параметра Тип Обязательное Правила Описание
api_version float yes maxLength: { max: 32 } QOD API версия
merchant_account string yes minLength: { min: 6 }, maxLength: { max: 32 } Аккаунт мерчанта
timestamp string yes unix timestamp Timestamp ответа
transactions \ chargebacks \ modifications array\null yes enum: {values: ["transactions”, ”chargebacks”, “modifications”]} показывает qod_type для запросов: transactions \ chargebacks \ modifications Can be unknown in case id qod_type was absent in request.
status string yes maxLength: { max: 10 } Неуспешный ответ должен содержать неуспешный статус
code string yes Length: {4 } код ответа QOD
message string no maxLength: { max: 255 } сообщение ответа QOD

Статусы ответа

Код Описание
success Успешный QOD ответ
error Неуспешный QOD ответ

Qod API специальные коды ответов:

Код Значение Сообщение (возможны изминения)
5000 QOD GENERAL ERROR QOD главная ошибка
5001 QOD UNSUPPORTED API VERSION неподдерживаемая QOD API версия
5002 INVALID TIME ORDER время с начала не может быть больше, чем время до

Баланс API

Баланс API позволяет получить данные по балансу на заданную дату. Метод Merchant_balance обеспечивает мультивалютный баланс для всех аккаунтов Мерчанта. Примечание: режим баланса (тестовый/живой) зависит от статуса аккаунта.

Среда для запросов URL
URL для живой среды https://gateway.genome.eu/api/frs
URL для тестовой среды /api/frs

Пример баланс запроса: "Content-type: JSON, POST" --data

{
    "api_version":1,
    "method": "MERCHANT_BALANCE",
    "merchant_account":"my_merchant_account",
    "merchant_password":"my_merchant_password",
    "time": 1504044107
}

Параметры для баланс запроса:

Параметр Обязательный Тип Описание
api_version да int API версия.
method да string MERCHANT_BALANCE метод.
merchant_account да string Мерчант аккаунт.
merchant_password да string Пароль для мерчант аккаунта.
time да int Заданная дата.

Пример ответа в JSON формате:

{
    "sessionid": "334133-5464-55a2214q-15e3c1b5721-4f55",
    "timestamp": 1504252111,
    "balance": [
        {
            "currency": "USD",
            "amount": 24401.17
        },
        {
            "currency": "EUR",
            "amount": -532.11
        }
    ],
    "status": "success",
    "code": 0,
    "message": "Request processed successfully"
}

Параметры ответа по баланс запросу:

Параметр Обязательный Тип Описание
sessionid да string ID сессии.
timestamp да int Bремя ответа.
balance[currency] да string Валюты процессинга.
balance[amount] да float\int Суммы процессинга.
status да string Статус.
code да int Код ответа.
message да string Описание ответа.

Коды ответов

Список кодов

Назначение: соответствующие коды передаются в каждом ответе. Описание запросов содержит расширенную информацию для описания результатов осуществленной транзакции.

Module Code Value Message (can be extended depending on case)
GENERAL 0 SUCCESS transaction processed successfully
1 GENERAL SYSTEM ERROR general system error
2 DATABASE ERROR internal DB error
3 INTERNAL SERVICE ERROR general internal service error
10 INTERNAL SERVICE COMM ERROR general internal service communication error
11 INTERNAL SERVICE TIMEOUT internal timeout
12 SERVICE SSL ERROR internal SSL error
1000 GENERAL MERCHANT GATE ERROR merchant gate error
1001 GENERAL MERCHANT GATE ERROR request format error
1002 MANDATORY FIELDS ARE MISSING [field] not present in request
1003 INTERNAL COMM ERROR internal communication error
1004 INVALID PARAMETER invalid [field] in request message
1005 UNSUPPORTED API VERSION unsupported API version
2000 GENERAL MMS ERROR all other errors
2001 INVALID MERCHANT ACC PASSWORD incorrect value in merchant account or pass field
2002 COUNTRY RESTRICTIONS country is not available
2003 MERCHANT ACC IS NOT ACTIVE merchant account exists but not active
2004 UNAUTHORIZED TRANSACTION transaction is not allowed to account
2005 MID NOT ACTIVE there is no MID configured for account
2006 CURRENCY NOT ACTIVE there is no currency configured for account
2007 AMOUNT RESTRICTIONS amount is below or above amount restrictions
2008 IP ADDRESS RESTRICTIONS access from this IP-address is not available
2009 MERCHANT NOT ACTIVE merchant is not activated
2010 GATE NOT ACTIVE gate is not active
2011 ENTITY_ALREADY_EXISTS entity already exists
2012 ENTITY_NOT_FOUND entity is not found
2013 BAD_MID_CREDENTIALS bad mid credentials
3000 GENERAL PROCESSING ERROR all other errors
3001 TRANSACTION UNIQUE ID ALREADY USED transaction ID/ Order ID is already used
3002 INVALID TOKEN token not found or invalid
3003 INVALID REFFERENCE reference not found or invalid
3004 VOID NOT POSSIBLE it is not possible to void the the provided reference
3005 REFUND NOT POSSIBLE it is not possible to refund the provided reference
3006 TRANSACTION IS CB transaction is chargebacked
3007 ILLEGAL INTERVAL illegal interval between AUTH and SETTLE/VOID, between AUTH 3D and SETTLE/SALE
3008 ALREADY VOIDED transaction was already voided
3009 ALREADY REFUNDED transaction was already refunded
3010 ALREADY SETTLED transaction was already settled
3011 CARD TYPE NOT SUPPORTED MID doesn’t support the card type
3012 ACCOUNT IS NOT 3D ENABLED account doesn't support 3D secure
3013 REQUIRED 3DS account support only 3D secure transaction
3014 TRANSACTION NOT FOUND FOR CHECK there was no transaction found on your Check request
3015 INVALID CURRENCY bank MID doesn’t support the currency
3016 WRONG SETTLE AMOUNT amount in settle transaction is incorrect
3017 WRONG MID CREDENTIALS bank MID access credentials are incorrect
3018 MID IP ERROR bank refused the connection
3019 VALIDATION FAILED request cannot be validated
3020 INVALID CHARGEBACK chargebacks is invalid
3021 TRANSACTION BLOCKED transaction is blocked by routing
3022 INCORRECT AMOUNT the amount is incorrect
3023 ABORTED TRANSACTION transaction is aborted by the customer
3024 EXPIRED TRANSACTION transaction is expired
3100 GENERAL BANK DECLINE transaction declined by bank network
3101 INSUFFICIENT FUNDS insufficient funds
3102 LOST/STOLEN CARD card lost or stolen
3103 3DSECURE AUTH FAILED 3d secure authentication failed
3104 INVALID CVV invalid CVV
3105 CARD EXPIRED card expired due to expiry date or expiry date is not correct
3106 INVALID AMOUNT bank cannot process selected amount
3107 INVALID CARD NUMBER card number was declined by bank
3108 REFUND LIMIT EXCEEDED it is not possible to issue refund due to bank limit
3109 TIMEOUT timeout between PSP and bank
3110 BANK REQUIRED FIELDS ARE MISSING OR INCORRECT not all required data was provided to the specific bank
3111 BANK ACCESS ERROR access error to a bank asquirer
3112 BANK CARD TYPE NOT SUPPORTED card type is not supported by MID
3113 BANK TRANSACTION TYPE NOT SUPPORTED transaction type is not supported by MID
3114 BANK CURRENCY NOT SUPPORTED currency is not supported by MID
3115 REFUND NOT POSSIBLE DO VOID order should be be voided due it was not settled
3116 COUNTRY NOT SUPPORTED country is not supported by MID
3117 MALFORMED BANK RESPONSE malformed bank response
3118 BANK_CONNECTION_ERROR bank connection error
3119 REFERAL OR RESTRICTED CARD Referal or restricted card
3120 RISK BANK DECLINE Risk Bank Decline
3121 INVALID ACQUIRER TOKEN acquirer token is invalid
3122 INVALID ACQUIRER REFERENCE acquirer reference is invalid
3123 ACQUIRER 3D SECURE NOT ENABLED acquirer 3D secure is not enabled
3124 UNKNOWN ACQUIRER PROCESSING STATUS unknown acquirer processing status
3125 ACQUIRER INTERNAL ERROR acquirer internal error
3126 WITHDRAWAL FREQUENCY LIMIT EXCEEDED withdrawal frequency limit exceeded
3127 BANK NEGATIVE LIST bank negative list
3128 FRAUD BANK DECLINE fraud decline by bank
3129 AUTHORIZATION DECLINED authorization decline
ANTIFRAUD 3200 GENERAL FRAUD DECLINE Declined by anti-fraud system
3201 GENERAL MANUAL REVIEW Sent for manual review by anti-fraud system
3220 TRUST LIST FRAUD DECLINE [Field] in black list
3221 TRUST LIST MANUAL REVIEW [Field] in watch list
Payout 3300 GENERAL DECLINE General payout error
3310 VALIDATION DECLINE Payout validation error
3311 INVALID MID REFERENCE Invalid mid reference
3330 UNREGISTERED CARD Unregistered card
FRS 4000 GENERAL RECONCILLIATION ERROR general reconcilliation error
4001 RECONCILLIATION INCOMPLETE reconcilliation incomplete
4002 RECONCILLIATION AMOUNT MISMATCH reconcilliation amount mismatch
4003 RECONCILLIATION COUNT MISMATCH reconcilliation count mismatch
4004 GENERAL FRS ERROR FRS general error
4005 BALANCE_IS_NOT_AVAILABLE Balance is not available
4006 CURRENCY_IS_NOT_AVAILABLE Currency is not available/td>
4007 EXCEEDED_AMOUNT Exceeded amount
QOD 5000 QOD GENERAL ERROR QOD general error
5001 QOD UNSUPPORTED API VERSION unsupported API version of QOD
5002 INVALID TIME ORDER time order is invalid
AUTH 6000 INTERNAL AUTH FAILURE general internal auth failure
6001 WRONG CREDENTIALS Wrong credentials
6002 ACCESS DENIED Access denied
6003 ALREADY EXISTS The user already exists
6004 USER NOT FOUND The user is not found
6005 ROLE NOT FOUND The role is not found
6006 PERMISSION NOT FOUND The permission is not found
6007 EXPIRED TOKEN The token is expired
6008 TOKEN NOT FOUND The token is not found
6009 USER TEMPORARY BLOCKED The user is temporary blocked
6010 EXPIRED PASSWORD The password is expired
6011 INVALID PASSWORD The password is invalid
6012 PREVIOUSLY USED PASSWORD The password is previously used
7000 INTERNAL PAYMENT GATE ERROR Internal payment gate error
7101 INTERNAL PAYMENT GATE SENDER ERROR Internal payment gate sender error
7102 COMMUNICATION ERROR External communication error
7103 COMMUNICATION TIMEOUT External communication timeout

Реагирование на код ответа

Код Результат транзакции Действия
0 SUCCESS
1 unknown CHECK transaction status
2 unknown CHECK transaction status
3 unknown CHECK transaction status
10 unknown CHECK transaction status
11 unknown CHECK transaction status
12 unknown CHECK transaction status
1003 unknown CHECK transaction status
6000 unknown CHECK transaction status
OTHER RC DECLINE

API libraries

Genome hosted payment page client

For hosted payment page integration you can use our has library on GitHub, where you can find:

Magento module

Module for Magento 1.9 is available on GitHub The installation process is described on GitHub.

Drupal module

Module for Drupal is available on GitHub The installation process is described on GitHub.