УКР | ENG

Підключення до системи 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].

Запит

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

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

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

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

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

{
  "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":

Приклади відповідей на запит [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).

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

Розглянемо детальніше роботу двоетапної схеми "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]

{
  "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

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

{
  "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": ""
}

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

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

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

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

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

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

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

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

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

• Користувач ще не почав сплачувати ("Reason":100051),
• Час очікування платежу сплинув ("Reason":100053).

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

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

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

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

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

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

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

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

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

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

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