owned this note changed 6 months ago
Published Linked with GitHub

УКР | ENG

Image Not Showing Possible Reasons
  • The image file may be corrupted
  • The server hosting the image is unavailable
  • The image path is incorrect
  • The image format is not supported
Learn More →
На Головну

Підключення до системи MTBMoney

Підключення до API

Підключення Партнера виконується методом виклику API XPAY. Для звернення до API XPAY використовується персональний токен Партнера.

Всі запити Партнера мають бути закриптовані з використанням алгоритму RSA (ключі RSA).

Для ідентифікації запиту в системах Партнера та Оператора необхідно використовувати структуру "Transaction".

Налаштування системи та тестові запити API виконуються на тестовому середовищі:

Адреса тестового середовища:

https://stage-papi.xpaydirect.com/xpay

Ключ для тестового середовища:

-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA0IH2V0Ot1ej4FdOihujG
ON37sqql62vFFR/4IK+w4xqHRvD+SEwwkLL9EO72e42bV9VaKOqKbX81A+0hbBXi
W7axjHU2Sc97EXTHjpwX++HduUXbXhRteyzcHDLZCGKT8WzoNgQeXcieLUYUp2bb
gjElGecKprcprkMeHmffmelwlzcv61auGU0o10CTyyCqhOKofdqJq6A2KOBCLL49
5z1700oCRo9qL4loe95r4wGh6AmHZNvAnAwLgzwzyLvWCz479CVIWEaMY/+uczfL
0yRjN+8uqNK3A09wOD+wO1I+YfU9YXcQ75L8ibxzWcNgMHrhJQ9ZtnoVltiTWEEB
9QIDAQAB
-----END PUBLIC KEY-----

Для роботи на продуктовому середовищі необхідно застосувати наступні дані:

Адреса продуктового середовища:

https://papi.xpaydirect.com/xpay

Ключ для продуктового середовища:

-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA9+1AEFfD9MoO0IWeMk3f    
aFoYBBekFgHmUGM48AVh6BW/s5r16mtUfMfRfezVgqluwV/liEd6hArmmEZIKwYE    
mJoAYuY/ny9QJpc8zY+toR5IJEtYxfStHmVwKSuvHL3KY/U/Ok5UUT2u075JPZb+
FtDZwW9KXkwmT53HQ6iS0XFyy621vGrs6XcdGwO6eZPptkvc8SYKDwClgLjI69Iz
b6K/dfdQUioMPvZOXpdzrEQXjnipmsYh1VxOufqsX1SDzqR67Zs114OnHWAZhTXE
ksUjKavJkCc07T+nu1O/r99rsrRCaQODVq8SMAoK1vxJLf29WFv4ydp4vIk+n98/
DQIDAQAB
-----END PUBLIC KEY-----

Приймання оплати

Для прийому оплати на рахунок Партнера застосовується запит [10005].

Переглянути повний опис запиту: [10005] "Отримання посилання на платіжну сторінку".

Запит

Опис атрибутів "Partner", "KeyAES" та "Sign" див. у розділі "Загальна інформація по підключенню (API)".

Структура "Data" для даної операції формується з наступних параметрів:

Параметр Обов’яз-ковість Тип Опис Приклад
PayType Ні Рядок Тип платіжного методу:
0 або відсутність параметра - пряме списання коштів з картки клієнта через с2а (card-to-account) або p2p (person-to-person) переказ;
1 - оплата через шлюз інтернет-еквайрингу;
2 - відкладений платіж1;
3 - оплата через сторонній віджет;
4 - оплата за реквізитами2;
5 - відкладений платіж за реквізитами1,2;
7 - пакетна оплата послуг;
12 - пакетна оплата послуг за реквізитами;
13 - оплата на користь мерчантів (MIDs);
20 - оплата через "Google/Apple Pay".
Див. деталі у розділі "Типи платіжного методу "PayType".
5

1 При проведенні запитів "відкладеного платежу" ("PayType":2 або "PayType":5) - Партнер додатково надсилає запит на "Підтвердження/скасування передавторизації". У разі відсутності підтвердження - списання коштів буде автоматично скасовано (через відрізок часу, вказаний у договорі з Партнером).

2 При проведенні запитів "оплати за реквізитами" ("PayType":4 або "PayType":5) - Оператор у відповідь надсилає запит "check", на який необхідно повернути дані реквізитів для оплати (див. розділ "[check] Протокол двостадійної взаємодії").

Параметр Обов’яз-ковість Тип Опис Приклад
Phone3 Ні Рядок Телефон клієнта у форматі: "380ххххххххх". 380961000000
Email3 Ні Рядок Email клієнта. index@gmail.com
Account3 Ні Рядок Ідентифікатор клієнта у системі Партнера: телефон або email. Дані клієнта, у ході обробки яких Оператор може надсилати зустрічний запит "check" Партнеру. 380961000000

3 Якщо в запиті не вказано жодного з цих параметрів (Phone, Email чи Account) - Оператор передає посилання на форму для їх введення клієнтом. Після отримання даних виконується запит "check" для уточнення деталей оплати. Серед полів Phone та Email більш пріоритетним є Phone. Якщо запит необхідно проводити за допомогою email-у, то його слід вказати у полі Account.

Параметр Обов’яз-ковість Тип Опис Приклад
FirstName Ні Рядок Ім'я клієнта. Олег
MiddleName Ні Рядок По батькові клієнта. Михайлович
LastName Ні Рядок Прізвище клієнта. Подільський
Address Ні Рядок Білінгова адреса клієнта. 456 Main Street
City Ні Рядок Місто клієнта. San Diego
CountryCode Ні Рядок Код країни клієнта (ISO CODES), згідно табл. "Country Codes". US
PostCode Ні Рядок Індекс клієнта. 92126
State Ні Рядок Штат клієнта. California (CA)
PaymentSum Ні Ціле Сума оплати у копійках. Параметр передається для відображення суми оплати на платіжній сторінці. При заповненому полі - Оператор не здійснює запит "check" для визначення суми оплати. 50грн.=>5000
Order Ні Рядок Номер замовлення. 1234А
Currency Так - при оплаті у валюті, відмінній від UAH Рядок Код валюти списання – скорочене буквене позначення валюти, описане в стандарті ISO 4217 (“GBP”, “USD”, ..). USD
Exchange Так - при оплаті у валюті, відмінній від UAH Рядок Код валюти зарахування – скорочене буквене позначення валюти, описане в стандарті ISO 4217 (“GBP”, “USD”, ..). GBP
Callback Ні Структура Складається з структури даних PaySuccess для обробки успішного платежу, де поле URL - адреса, на яку буде перенаправлений клієнт після завершення оплати. https://partner.com/payment_success
CallBackURL Ні Рядок Адреса Партнера, на яку виконуються запити "check" та "pay / error / refund" для сповіщення про результати оплати. https://partner.com/callback
MIDs4 Ні Масив Масив, що передає дані для розщеплення прийнятого платежу на користь мерчантів. Див. приклад нижче.
PaymentInfo5 Ні Масив Параметр передається для відображення деталей платежу на сторінці оплати. Див. приклад нижче.
Transaction Так Структура Структура, що передає дані про транзакцію. Див. розділ "Структура "Transaction". Див. нижче.

4 Параметри масиву "MIDs":

Параметр Обов’яз-ковість Тип Опис Приклад
MID Так Ціле Ідентифікатор мерчанта в системі Оператора (Merchant ID), на який зараховуються кошти. 111
Sum Так Ціле Сума платежу у копійках. 1грн.=>100
PaymentInfo5 Ні Масив Параметр передається для відображення деталей платежу на сторінці оплати. Див. приклад нижче.
Account Ні Рядок Розрахунковий рахунок або IBAN одержувача (міжнародний номер банківського рахунку). UA4830529900000 26008031203677
EDRPOU Ні Рядок ЄДРПОУ одержувача. 3505506226
MFO Ні Рядок МФО - код банку одержувача. 305299
Name Ні Рядок Назва одержувача. ТОВ "Ресурс"

5 Параметри масиву "PaymentInfo":

Параметр Обов’яз-ковість Тип Опис Приклад
Caption Так Рядок Опис додаткової інформації. Призначення
Value Так Рядок Додаткова інформація. Оплата за замовлення №1 від 08.04.2024 клієнт ПІБ

Приклад запиту [10005]

Приклад структури "Data"
{
  "Account": "test@gmail.com",
  "Email": "mtest@gmail.com",
  "FirstName": "Ім'я",
  "LastName": "Прізвище",
  "MiddleName": "",
  "Callback": {
    "PaySuccess": {
      "URL": "https://partner.com/payment_success"
    }
  },
  "CallBackURL": "https://partner.com/callback",
  "Currency": "UAH",
  "Exchange": "EUR",
  "MIDs": [
    {
      "Account": "IBAN",
      "EDRPOU": "123",
      "MFO": "AAAA",
      "MID": "ID",
      "PaymentInfo": [
        {
          "Caption": "Призначення",
          "Value": "Оплата за замовлення №1 від 08 April 2024 клієнт ПІБ"
        }
      ],
      "Sum": 250
    }
  ],
  "Order": "124",
  "PaymentInfo": [
    {
      "Caption": "Призначення",
      "Value": "Оплата за товар №1 від 08 April 2024 від ПІБ"
    }
  ],
  "PaymentSum": 100,
  "PayType": "13",
  "Phone": "+380961000000",
  "Transaction": {
    "DateTime": "20240408 16:43:21",
    "TerminalID": "1",
    "TransactionID": "bb61-55b500d61f25"
  }
}

Відповідь

Загальна інформація по формуванню структури відповіді наведена у розділі “Загальна інформація по підключенню (API)”.

Успішна відповідь на запит [10005] містить посилання у вигляді рядка з ім'ям "URI" у структурі "Data":

Параметр Обов’яз-ковість Тип Опис Приклад
URI Так Рядок Посилання на платіжну сторінку (Checkout). https://stage-mapi.xpaydirect.com/uk/frame/widget/691fafc9-5d64-46b5-22ba-85ce61cc26be
uuid Так Рядок Унікальний ідентифікатор, що зв'язує запити "check" та "pay". f3cd72b6-e1ea-406f-9b44-a9b93b401b7f

Приклади відповідей на запит [10005]

Операція проведена успішно
{
  "Code": 200,
  "Message": "done",
  "Data": {
    "OperationDate": "2024-04-08T17:43:22.40934+03:00",
    "OperationID": 1,
    "OperationStatus": 10,
    "URI": "https://mapi.xpaydirect.com/en/frame/widget/93c4*****4-d52e-4e07-85fd-3****b6bd60",
    "uuid": "93c4*****4-d52e-4e07-85fd-3****b6bd60"
  },
  "KeyAES": "",
  "Sign": ""
}
Помилка виконання операції
{
  "Code": 200,
  "Message": "done",
  "Data": {
    "OperationID": 111,
    "OperationStatus": 21,
    "Reason": 3
  },
  "KeyAES": "",
  "Sign": ""
}

Протокол двостадійної взаємодії

Коли платіжна сторінка Партнера передбачає авторизацію клієнта (введення телефону/email), та у ході обробки даних на стороні Оператора виникає необхідність перевірки реквізитів оплати та/або уточнення суми оплати - застосовується протокол двостадійної взаємодії.

Див. деталі у розділі: "[check] Протокол двостадійної взаємодії".

Запити "pay/error/refund" (CallBackURL)

Завершальним етапом у виконанні операції є надсилання нотифікацій Партнеру про статус операції у вигляді одного з запитів:

  • "pay" (оплата завершена),
  • "error" (помилка оплати),
  • "refund" (здійснено повернення).

Див. деталі у розділі: "[pay/error/refund] Статус операції (CallBackURL)".

Виплати

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

Виплата на картку може проводитись по одному з двох сценаріїв:

1. За один крок - "Payouts (one step)" - в результаті надсилання запиту на проведення виплати [10301/10311/103013] "Гаманець-карта" Партнер отримує відповідь про статус операції: успіх ("OperationStatus": 10) або помилку ("OperationStatus": 21/22).

image

Де: Client - клієнт Партнера, APP - мобільний додаток Партнера, XPAY - Оператор,
PS (Payment System) - платіжна система (Visa, Mastercard та ін.).

2. У два кроки - "Payouts (two steps)" - в результаті надсилання запиту на проведення виплати [10301/10311/103013] "Гаманець-карта" Партнер: а) отримує розрахунок суми списання (+комісії) у відповідній валюті; б) надсилає підтвердження/скасування операції по виплаті через надсилання запитів [10001/10002].

image

Розглянемо детальніше роботу двоетапної схеми "Payouts (two steps)":

  • Клієнт через додаток Партнера ініціює зарахування коштів на картку.
  • Партнер надсилає запит [20001] до системи XPAY, щоб отримати доступний баланс гаманця для проведення виплати, та передає в нього ID гаманця для виплат (який можна отримати в Оператора на етапі інтеграції).
  • Якщо сума залишку на гаманці Партнера достатня (The balance is sufficient) - Партнер надсилає запит на проведення виплати [10301/10311/103013] "Гаманець-карта".
  • Оператор розраховує та бронює суму списання (+комісію) у відповідній валюті (Ammount+Fee in currency).
  • Додаток Партнера відображає клієнту загальну суму списання (Withdrawal amount).
  • Клієнт а) підтверджує загальну суму списання (Payment confirmation) -> Партнер надсилає запит на підтвердження операції [10001] -> Платіжна система здійснює виплату (Replenishment); або б) скасовує загальну суму списання (Payment cancellation or timeout) -> Партнер надсилає запит на скасування операції [10002].
  • В завершення - клієнту відображається результат підтвердження/скасування зарахування коштів на картку, а Партнер отримує відповідь від Оператора про статус операції: успіх ("OperationStatus": 10) або помилку ("OperationStatus": 21/22).

Приклад запиту [103013]

Приклад структури "Data"
{
  "MIDs": [
    {
      "MID": "1258725",
      "Sum": 403850
    }
  ],
  "Purpose": "Повернення коштiв",
  "Transaction": {
    "DateTime": "20240423 10:42:34",
    "TerminalID": "1",
    "TransactionID": "1610"
  },
  "TransferA2C": {
    "Sum": 403850,
    "LastName": "LastName",
    "FirstName": "FirstName",
    "RecipientCard": {
      "IPN": "1111111111",
      "PAN": "4441********3330",
      "LastName": "LastName",
      "FirstName": "FirstName",
      "MiddleName": "MiddleName"
    }
  }
}

Приклади відповідей на запит [103013]

Операція проведена успішно
{
  "Code": 200,
  "Data": {
    "result": "OK",
    "OperationID": 2234,
    "OperationDate": "2024-04-23T10:42:46.262885+03:00",
    "OperationStatus": 10
  },
  "Sign": "",
  "KeyAES": "",
  "Message": ""
}
Помилка виконання операції
{
  "Code": 200,
  "Message": "done",
  "Data": {
    "OperationID": 2234,
    "OperationDate": "2024-04-23T10:42:46.262885+03:00",
    "OperationStatus": 21,
    "Reason": 3
  },
  "KeyAES": "",
  "Sign": ""
}

Виплата на IBAN

Для проведення виплати на IBAN, що використовується для CJ, застосовується запит: [10303] "Гаманець-IBAN".

Приклад запиту [10303]

Приклад структури "Data"
{
  "Currency": "UAH",
  "Email": null,
  "Exchange": "UAH",
  "Phone": null,
  "Purpose": "CJ; Переказ коштів; payment of fees, bonuses, prizes, and other payments from non-residents of Ukraine abroad for the use of their works, inventions; реєстраційний номер фактичного платника BC1****73; код країни відправника 826",
  "RecipientPerson": {
    "Account": "UA093****94990",
    "Address": "M****b",
    "Birthday": null,
    "Birthplace": null,
    "City": "Zhytomyr",
    "CountryCode": "UA",
    "Email": null,
    "FirstName": "Y***v",
    "IPN": "3****6",
    "LastName": "Z***k",
    "MiddleName": "",
    "Phone": null,
    "PostCode": "1***2",
    "State": ""
  },
  "Sender": {
    "Account": null,
    "ActualCountry": "124",
    "Building": "-",
    "City": "Vancouver",
    "Country": "124",
    "CountryResidence": null,
    "EDRPOU": null,
    "MFO": null,
    "Name": "***a Inc",
    "Street": "ds St, Suite "
  },
  "Sum": 68900,
  "Transaction": {
    "DateTime": "20240419 07:10:05",
    "TerminalID": "0",
    "TransactionID": "test12"
  }
}

Приклади відповідей на запит [10303]

Операція проведена успішно
{
  "Code": 200,
  "Data": {
    "result": "OK",
    "OperationID": 2234,
    "OperationDate": "2024-04-23T10:42:46.262885+03:00",
    "OperationStatus": 10
  },
  "Sign": "",
  "KeyAES": "",
  "Message": ""
}
Помилка виконання операції
{
  "Code": 200,
  "Message": "done",
  "Data": {
    "OperationID": 2234,
    "OperationDate": "2024-04-23T10:42:46.262885+03:00",
    "OperationStatus": 21,
    "Reason": 3
  },
  "KeyAES": "",
  "Sign": ""
}

Отримання даних по проведеній операції

Перевірка балансу гаманця

Для отримання поточного балансу гаманця застосовується запит: [20001] "Отримання балансу гаманця".

Перевірка статусу операції

Всі операції та статуси їх обробки доступні в особистому кабінеті Партнера, або в реєстрі оплат, отриманому на пошту Партнера на наступний день операції.

Для перевірки поточного статусу операції застосовується запит: [20003] "Отримання статусу операції".

Коди відповідей та ознаки фатальності див. у таблиці: "Коди відповідей Оператора "Code".

Отримання http-коду з ознакою фатальності "ні" передбачає продовження виконання операції у системі Оператора чи Партнера.

Для запиту поточного статусу обробки операції необхідно повторювати запит [20003] з надісланими раніше параметрами до отримання http-коду з ознакою фатальності “так”. У відповіді змінюватиметься статус проведення операції.

Надсилання повторного запиту Оператору здійснюється: не частіше 1-го разу за 60 сек.

Час на надсилання відповіді обмежений та складає 55 сек. Якщо обробка операції не завершена - система XPAY формує відповідь з кодом 102.

Отримання timeout на будь-який API запит, в тому числі на запит статусу - необхідно розцінювати, як відповідь з кодом 102 та продовжувати запитувати статус до отримання фатального коду.

Для запиту [10005] додатково реалізовано два стани обробки операції:

  • Користувач ще не почав сплачувати ("Reason":100051),
  • Час очікування платежу сплинув ("Reason":100053).
Код відповіді Повідом-лення Статус OperationStatus Причина Reason Стан оплати
102 Processing 7 100051 Користувач не почав оплату.
102 Processing 5 будь-яка Операція в обробці.
200 Error 21 100053 Час очікування платежу сплинув.
200 Error 21 будь-яка Виникла помилка оплати. Див. опис у таблиці "Коди причин відхилення операцій".
200 Ok 10 відсутня Обробка операції завершена.

Див. деталі у розділі "Довідкові матеріали".

Порядок тестування на тестовому середовищі

Для тестування будь-яких операцій та ознайомлення з сервісами системи XPAY заведено Тестового Партнера. Див. деталі підключення у розділі: "Параметри підключення Тестового Партнера".

Порядок тестування на продуктовому середовищі

Для тестування операцій на продуктовому середовищі необхідно перевірити коректність виконання, як мінімум, чотирьох операцій:

  • з карткою Visa;
  • з карткою MasterCard;
  • успішну;
  • не успішну.

По "успішним" операціям необхідно перевірити наявність та коректність квитанцій про оплату. По "успішним/не успішним" - перевірити коректність їх відображення в кабінеті Партнера. За наявності надсилання "колбеків" - перевірити надходження та коректне їх опрацювання в системі Партнера.

Перегляд транзакцій в кабінеті

Щоб отримати повну інформацію по проведеним операціям необхідно в кабінеті Партнера перейти до розділу "Аналітика".

image

Отримання реєстру

Спосіб, у який будуть формуватися реєстри по операціям, визначається на етапі інтеграції Партнера:

image

Довідкові матеріали

Опис загальних параметрів системи XPAY див. у розділі "Довідкові матеріали": коди типів операцій, типи платіжних методів, коди статусів обробки операцій, відомості та помилки, що повертаються у відповіді та ін.


Image Not Showing Possible Reasons
  • The image file may be corrupted
  • The server hosting the image is unavailable
  • The image path is incorrect
  • The image format is not supported
Learn More →
На Головну
Image Not Showing Possible Reasons
  • The image file may be corrupted
  • The server hosting the image is unavailable
  • The image path is incorrect
  • The image format is not supported
Learn More →
Загальна інформація по підключенню (API)

Служба підтримки XPAY

Телефон: +38 093 891 92 00
Email: info@xpay.com.ua
Telegram: @xpaysupportbot

Select a repo