[10005] Отримання посилання на платіжну сторінку

УКР | [ENG](https://hackmd.io/qSkRHz6gRKmxNrWRwwrjqg) ![](https://i.imgur.com/ULmPUgP.jpg) :arrow_left: [На Головну](/Mj2ZqCVpSq6A6Jzm6ladlw) # [10005] Отримання посилання на платіжну сторінку :::info [TOC] ::: *Що таке Checkout, типи платежів та методи інтеграції див. у розділі ["Checkout"](https://hackmd.io/0mVv8NSpR1SBlFDoUtK5GQ).* :::warning За замовчуванням платіжна сторінка доступна протягом 15 хвилин. За необхідності, даний відрізок часу може змінюватись у параметрі `TTL` в структурі "Data" (див. нижче) або встановлюватись в налаштуваннях системи Оператора. ::: ## Запит *Опис атрибутів "Partner", "KeyAES" та "Sign" див. у розділі ["Загальна інформація по підключенню (API)"](https://hackmd.io/g3cItPVFStez0ql3Xj-2TA).* ### Структура "Data" Структура "Data" для даної операції формується з наступних параметрів: :::info <details> <summary>Формування структури "Data" (приклади наведені нижче)</summary> ~~~ { "PayType": "", "Phone": "", "Email": "", "Account": "", "FirstName": "", "LastName": "", "MiddleName": "", "IPN": "", "PaymentSum": , "Order": "", "Purpose": "", "ClientIP": "", "PanSuffix": "", "Currency": "", "Exchnge": "", "Signature": "", "AccountID": "", "BrowserFingerprint": "", "RecipientCard": { "PAN": "", "FirstName": "", "MiddleName": "", "LastName": "", "IPN": "", "document_type_id": "", "doc_series": "", "doc_number": "", "dt_doc_issue": "", "dt_doc_exp": "", "doc_issued_by": "" }, "MIDs": [ { "MID": , "Sum": , "PaymentInfo": [ { "Caption": "", "Value": "" } ], "Account": "", "EDRPOU": "", "MFO": "", "Name": "" } ], "PaymentInfo": [ { "Caption": "", "Value": "" } ], "Service": [ { "ServiceCode": "", "Sum": } ], "Callback": { "PaySuccess": { "URL": "" } }, "BillAttr": { "PayerAddress": "" }, "TTL": "", "CallBackURL": "", "AccountPayments": [ { "Sum": , "Purpose": "", "Account": "", "EDRPOU": "", "ID": "", "RecipientName": "", "SenderName": "", "IPN": "" } ], "ticket": [], "Transaction": { "TransactionID": "", "TerminalID": "", "DateTime": "" } } ~~~ </details> ::: | Параметр | Обов’яз-ковість | Тип | Опис | Приклад | |:-:|:-:|:-:|-|:-:| | `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"](https://hackmd.io/aBE7H5cfQ-iqaN3SnwaQ-w?view#%D0%A2%D0%B8%D0%BF%D0%B8-%D0%BF%D0%BB%D0%B0%D1%82%D1%96%D0%B6%D0%BD%D0%BE%D0%B3%D0%BE-%D0%BC%D0%B5%D1%82%D0%BE%D0%B4%D1%83-PayType). | `5` | :::warning ^1^ При проведенні запитів "відкладеного платежу" (`"PayType":2` або `"PayType":5`) - Партнер додатково надсилає запит на "[Підтвердження/скасування передавторизації](https://hackmd.io/aTXOGiPaSkewvXdXUbpstg)". У разі відсутності підтвердження - списання коштів буде автоматично скасовано (через відрізок часу, вказаний у договорі з Партнером). ^2^ При проведенні запитів "оплати за реквізитами" (`"PayType":4` або `"PayType":5`) - Оператор у відповідь надсилає запит "check", на який необхідно повернути дані реквізитів для оплати (див. розділ ["[check] Протокол двостадійної взаємодії"](https://hackmd.io/kk2x9Wx8QSe_vV11tA-KFA)). ::: | Параметр | Обов’яз-ковість | Тип | Опис | Приклад | |:-:|:-:|:-:|-|:-:| | `Phone`^3^ | Ні | Рядок | Телефон клієнта у форматі: "380ххххххххх". |`380679335544`| | `Email`^3^ | Ні | Рядок | Email клієнта. |`index@gmail.com`| | `Account`^3^ | Ні | Рядок |Ідентифікатор клієнта у системі Партнера: телефон або email. Дані клієнта, у ході обробки яких Оператор може надсилати зустрічний запит "[check](https://hackmd.io/kk2x9Wx8QSe_vV11tA-KFA)" Партнеру. |`380638754213`| :::warning ^3^ Якщо в запиті не вказано жодного з цих параметрів (`Phone`, `Email` чи `Account`) - Оператор передає посилання на форму для їх введення клієнтом. Після отримання даних виконується запит "[check](https://hackmd.io/kk2x9Wx8QSe_vV11tA-KFA?view)" для уточнення деталей оплати. Серед полів `Phone` та `Email` більш пріоритетним є `Phone`. Якщо запит необхідно проводити за допомогою email-у, то його слід вказати у полі `Account`. ::: | Параметр | Обов’яз-ковість | Тип | Опис | Приклад | |:-:|:-:|:-:|-|:-:| | `FirstName` | Ні | Рядок | Ім'я клієнта. |`Олег`| | `MiddleName` | Ні | Рядок | По батькові клієнта. |`Михайлович`| | `LastName` | Ні | Рядок | Прізвище клієнта. |`Подільський`| | `IPN` | Умовно-обов’язковий (визначається на етапі інтеграції) | Рядок | Індивідуальний податковий номер (ІПН) платника. |`111111111111`| |`RecipientCard`^4^|Ні|Структура|Структура, що передає дані банківської картки одержувача.|Див. нижче.| | `PaymentSum` | Ні | Ціле | Сума оплати у копійках. Параметр передається для відображення суми оплати на платіжній сторінці. При заповненому полі - Оператор не здійснює запит "[check](https://hackmd.io/kk2x9Wx8QSe_vV11tA-KFA)" для визначення суми оплати. |50грн.=>`5000`| | `Order` | Ні | Рядок |Номер замовлення. |`1234А`| | `Purpose` |Ні| Рядок | Призначення платежу. |`Оплата замовлення №543345`| | `ClientIP` | Ні | Рядок | IP адреса, з якої клієнт ініціює операцію. |`127.0.0.1`| | `PanSuffix` | Ні | Рядок | Останні 4 цифри номера картки, у разі, якщо відбулась попередня верифікація картки. |`3456`| | `Currency` | Так - при оплаті у валюті, відмінній від UAH | Рядок | Код валюти *списання* – скорочене буквене позначення валюти, описане в стандарті [ISO 4217](https://uk.wikipedia.org/wiki/%D0%9A%D0%BB%D0%B0%D1%81%D0%B8%D1%84%D1%96%D0%BA%D0%B0%D1%86%D1%96%D1%8F_%D0%B2%D0%B0%D0%BB%D1%8E%D1%82_(ISO_4217)) (“GBP”, “USD”, ..). |`USD`| | `Exchange` | Так - при оплаті у валюті, відмінній від UAH | Рядок | Код валюти *зарахування* – скорочене буквене позначення валюти, описане в стандарті [ISO 4217](https://uk.wikipedia.org/wiki/%D0%9A%D0%BB%D0%B0%D1%81%D0%B8%D1%84%D1%96%D0%BA%D0%B0%D1%86%D1%96%D1%8F_%D0%B2%D0%B0%D0%BB%D1%8E%D1%82_(ISO_4217)) (“GBP”, “USD”, ..). |`GBP`| | `BrowserFingerprint` | Ні | Рядок | [Цифровий відбиток браузера](https://uk.wikipedia.org/wiki/%D0%A6%D0%B8%D1%84%D1%80%D0%BE%D0%B2%D0%B8%D0%B9_%D0%B2%D1%96%D0%B4%D0%B1%D0%B8%D1%82%D0%BE%D0%BA_%D0%BF%D1%80%D0%B8%D1%81%D1%82%D1%80%D0%BE%D1%8E): [https://m.habr.com/ru/company/oleg-bunin/blog/321294/](https://m.habr.com/ru/company/oleg-bunin/blog/321294/); [https://github.com/valve](https://github.com/valve) |`86a190af26de3a920c62ea19ba0df3a8`| | `BillAttr` | Ні | Структура | Складається зі структури `PayerAddress`, що передає дані про зворотну адресу клієнта. |`м. Харків, вул. Хіміків 4/59`| | `Callback` | Ні | Структура | Складається з структури даних `PaySuccess` для обробки успішного платежу, де поле `URL` - адреса, на яку буде перенаправлений клієнт після завершення оплати. |`https://partner.com/callback/xpay1`| | `CallBackURL` | Ні | Рядок | Адреса Партнера, на яку виконуються запити "[check](https://hackmd.io/kk2x9Wx8QSe_vV11tA-KFA)" та "[pay / error / refund](https://hackmd.io/2x_MsqZIT6epfiqcQimFwQ)" для сповіщення про результати оплати. |`https://partner.com/callback/xpay2`| | `TTL` | Ні | Ціле | Час, протягом якого доступна сторінка для оплати. Параметр вказується в секундах. |`300`| |`Transaction`|Так|Структура|Структура, що передає дані про транзакцію. Див. розділ ["Структура "Transaction"](https://hackmd.io/g3cItPVFStez0ql3Xj-2TA#2-Data).|Див. нижче.| ^4^ Параметри структури **"RecipientCard"**: | Параметр | Обов'яз-ковість | Тип | Опис | Приклад| |:----:|:----:|:----:|----|:----:| |`PAN`|Так|Рядок[16]| PAN картки одержувача (номер банківської карти).| `8888888888888888`| | `FirstName` | Так* | Рядок | Ім'я одержувача. |`Максим`| | `MiddleName` | Так* | Рядок | По батькові одержувача. |`Олегович`| | `LastName` | Так* | Рядок | Прізвище одержувача. |`Кравець`| | `IPN` | Так* | Рядок | Індивідуальний податковий номер (ІПН) одержувача. |`111111111111`| | `document_type_id` | Так* | Ціле | Тип документа з довідника: `1` - паспорт, `2` - ID-картка. |`1`| | `doc_series` | Так* | Рядок | Серія документа. |`19910824-00026`| | `doc_number` | Так* | Рядок | Номер документа. |`123456789`| | `dt_doc_issue` | Так* | Рядок | Дата видачі документа. |`2022-06-14`| | `dt_doc_exp` | Так* | Рядок | Термін закінчення дії документа. |`2022-06-14`| | `doc_issued_by` | Так* | Рядок | Орган, що видав документ. |`3459`| **Параметри є умовно-обов’язковими (визначаються на етапі інтеграції).* Розглянемо параметри атрибуту "Data", що мають **структуру масивів**. #### Масив "MIDs" | Параметр | Обов’яз-ковість | Тип | Опис | Приклад | |:-:|:-:|:-:|-|:-:| | `MIDs` | Ні | Масив | Масив, що передає дані для розщеплення прийнятого платежу на користь мерчантів. |Див. приклад нижче.| Параметри масиву **"MIDs"**: | Параметр | Обов’яз-ковість | Тип | Опис | Приклад | |:-:|:-:|:-:|-|:-:| | `MID` |Так| Ціле | Ідентифікатор мерчанта в системі Оператора (Merchant ID), на який зараховуються кошти. |`111`| | `Sum` |Так| Ціле | Сума платежу у копійках.|1грн.=>`100` | | `PaymentInfo` | Ні | Масив | Параметр передається для відображення деталей платежу на сторінці оплати. |Див. приклад нижче.| | `Account` |Ні| Рядок | Розрахунковий рахунок або IBAN одержувача (міжнародний номер банківського рахунку). | `UA4830529900000 26008031203677`| |`EDRPOU`|Ні|Рядок | [ЄДРПОУ](https://uk.wikipedia.org/wiki/%D0%84%D0%B4%D0%B8%D0%BD%D0%B8%D0%B9_%D0%B4%D0%B5%D1%80%D0%B6%D0%B0%D0%B2%D0%BD%D0%B8%D0%B9_%D1%80%D0%B5%D1%94%D1%81%D1%82%D1%80_%D0%BF%D1%96%D0%B4%D0%BF%D1%80%D0%B8%D1%94%D0%BC%D1%81%D1%82%D0%B2_%D1%82%D0%B0_%D0%BE%D1%80%D0%B3%D0%B0%D0%BD%D1%96%D0%B7%D0%B0%D1%86%D1%96%D0%B9_%D0%A3%D0%BA%D1%80%D0%B0%D1%97%D0%BD%D0%B8) одержувача.|`3505506226` | | `MFO` |Ні |Рядок | [МФО](https://uk.wikipedia.org/wiki/%D0%9C%D0%A4%D0%9E) - код банку одержувача. |`305299`| | `Name` | Ні | Рядок | Назва одержувача. |`ТОВ "Ресурс"`| :::success <details> <summary>Приклад масиву даних "MIDs"</summary> ~~~md { "MIDs": [ { "MID": 111, "PaymentInfo": [ { "Caption": "Призначення", "Value": "Погашення за контрактом №3642989012-5 від 03.04.2021 Пупкіна Валерія Сергіївна" } ], "Sum": 100, "Account": "UA483052990000000008031203000", "EDRPOU": "3505501111", "MFO": "123456" }, { "MID": 112, "PaymentInfo": [ { "Caption": "Призначення", "Value": "Погашення за контрактом №3642989012-5 від 03.04.2021 Пупкіна Валерія Сергіївна" } ], "Sum": 200, "Account": "UA483052990000000008031203000", "EDRPOU": "3505501111", "MFO": "123456" } ] } ~~~ </details> ::: #### Масив "PaymentInfo" | Параметр | Обов’яз-ковість | Тип | Опис | Приклад | |:-:|:-:|:-:|-|:-:| | `PaymentInfo` | Ні | Масив | Параметр передається для відображення деталей платежу на сторінці оплати. |Див. приклад нижче.| Параметри масиву **"PaymentInfo"**: | Параметр | Обов’яз-ковість | Тип | Опис | Приклад | |:-:|:-:|:-:|-|:-:| | `Caption` |Так| Рядок | Опис додаткової інформації. |`Призначення`| | `Value` |Так| Рядок | Додаткова інформація. |`Погашення за контрактом №3642989012-5 від 03.04.2021 Пупкіна Валерія Сергіївна`| :::success <details> <summary>Приклад масиву даних "PaymentInfo"</summary> Необхідно відобразити на платіжній сторінці: "Призначення: Погашення за контрактом №3642989012-5 від 03.04.2021 Пупкіна Валерія Сергіївна" ~~~md { "PaymentInfo": [ { "Caption": "Призначення", "Value": "Погашення за контрактом №3642989012-5 від 03.04.2021 Пупкіна Валерія Сергіївна" } ] } ~~~ </details> ::: #### Масив "RegistryAttr" | Параметр | Обов’яз-ковість | Тип | Опис | Приклад | |:-:|:-:|:-:|-|:-:| | `RegistryAttr` | Ні | Масив | Параметр застосовується для формування та відправки звітів Партнера. |Див. приклад нижче.| Параметри масиву **"RegistryAttr"**: | Параметр | Обов’яз-ковість | Тип | Опис | Приклад | |:-:|:-:|:-:|-|:-:| | `Caption` |Так| Рядок | Назва поля, що відображається у файлі звітності. |`acc_id`| | `Value` |Так| Рядок | Значення поля, що відображається у файлі звітності.|`123`| :::success <details> <summary>Приклад масиву даних "RegistryAttr"</summary> ~~~md { "RegistryAttr": [ { "Caption": "acc_id", "Value": "123" }, { "Caption": "mdf_id", "Value": "11011" } ] } ~~~ </details> ::: #### Масив "Service" | Параметр | Обов’яз-ковість | Тип | Опис | Приклад | |:-:|:-:|:-:|-|:-:| | `Service`^5^ | Ні | Масив `ServiceItem` | Масив даних, що передається для оплати пакета послуг. Кожен платіж описується назвою послуги та сумою оплати за послугу. |Див. приклад нижче.| :::warning ^5^ Параметр передається лише при проведенні запиту [пакетної оплати послуг](https://hackmd.io/aBE7H5cfQ-iqaN3SnwaQ-w?both#%D0%A2%D0%B8%D0%BF%D0%B8-%D0%BF%D0%BB%D0%B0%D1%82%D1%96%D0%B6%D0%BD%D0%BE%D0%B3%D0%BE-%D0%BC%D0%B5%D1%82%D0%BE%D0%B4%D1%83-%E2%80%9CPayType%E2%80%9D) (`"PayType":7`), тобто розщеплення платежу клієнта на декількох одержувачів та зарахування коштів на заздалегідь прописані гаманці. ::: Параметри масиву **"ServiceItem"**: | Параметр | Обов’яз-ковість | Тип | Опис | Приклад | |:-:|:-:|:-:|-|:-:| | `ServiceCode` | Так |Рядок | Буквено-цифрова назва послуги або її постачальника. Перелік даних значень є індивідуальним та визначається в залежності від послуг, що надаються Партнером.|`TEPLO`| | `Sum` | Так | Ціле | Сума платежу за послугою у копійках. |1грн.=>`100`| :::success <details> <summary>Приклад масиву даних "ServiceItem"</summary> ~~~md { "Service": [ { "ServiceCode": "TEPLO", "Sum": 5500 }, { "ServiceCode": "GAZ", "Sum": 12000 } ] } ~~~ </details> ::: #### Масив "AccountPayments" | Параметр | Обов’яз-ковість | Тип | Опис | Приклад | |:-:|:-:|:-:|-|:-:| | `AccountPayments`^6^ | Ні | Масив `AccountPayment` | Масив даних, що передається для оплати пакета послуг за реквізитами. Кожен платіж описується набором параметрів, наведених нижче.|Див. приклад нижче.| :::warning ^6^ Параметр передається лише при проведенні запиту [пакетної оплати послуг за реквізитами](https://hackmd.io/aBE7H5cfQ-iqaN3SnwaQ-w?both#%D0%A2%D0%B8%D0%BF%D0%B8-%D0%BF%D0%BB%D0%B0%D1%82%D1%96%D0%B6%D0%BD%D0%BE%D0%B3%D0%BE-%D0%BC%D0%B5%D1%82%D0%BE%D0%B4%D1%83-%E2%80%9CPayType%E2%80%9D) (`"PayType":12`), тобто розщеплення платежу клієнта на декількох одержувачів та зарахування коштів на вказані реквізити. ::: Параметри масиву **"AccountPayments"**: | Параметр | Обов’яз-ковість | Тип | Опис | Приклад | |:-:|:-:|:-:|-|:-:| | `Sum` |Так| Ціле | Сума платежу за послугою у копійках. | 1 грн.=>`100` | | `Purpose` |Так| Рядок | Призначення платежу. |`Оплата замовлення №543345`| | `Account` |Так| Рядок | IBAN отримувача (міжнародний номер банківського рахунку). | `UA173052990000026207893720887`| | `EDRPOU` |Так| Рядок | ЄДРПОУ отримувача. | `34190717` | | `ID` |Так| Рядок | Унікальний ідентифікатор платежу. |`af1377`| | `RecipientName` |Так| Рядок | ПІБ отримувача платежу. |`Шевченко Т.Г.`| | `SenderName` |Так| Рядок | ПІБ відправника платежу.|`Дзюба А.І.`| | `IPN` |Так| Рядок | Індивідуальний податковий номер платника податків. |`7845325697`| :::success <details> <summary>Приклад масиву даних "AccountPayment"</summary> ~~~md { "AccountPayments": [ { "Sum": 10000, "Purpose": "Оплата замовлення №543345", "Account": "UA173052990000026207893720887", "EDRPOU": "34190717", "ID": "af1377", "RecipientName": "Шевченко Т.Г.", "SenderName": "Дзюба А.І.", "IPN": "7845325697" }, { "Sum": 20000, "Purpose": "Оплата замовлення №543000", "Account": "UA173052990000026207893765656", "EDRPOU": "33230717", "ID": "af12277", "RecipientName": "Муляр О.В.", "SenderName": "Дзюба А.І.", "IPN": "7845325697" } ] } ~~~ </details> ::: #### Масив "ticket" Параметр `ticket` застосовується для формування **фіскального чека** на програмному касовому апараті. | Параметр | Обов’яз-ковість | Тип | Опис | Приклад | |:-:|:-:|:-:|-|:-:| | `ticket`^7^ | Ні | Масив `ticket` | Масив даних, що передає інформацію про товар: ідентифікатор товару, найменування, вартість та кількість. | Див. приклад нижче. | | `cashiersignature` | Ні | Рядок | Підпис касира. Параметр передається лише при необхідності фіскалізації операції та формування [РРО](https://tax.gov.ua/baneryi/programni-rro/aktualni-zapitannya-vidpovidi/) квитанцій ([реєстратор розрахункових операцій](https://uk.wikipedia.org/wiki/%D0%A0%D0%B5%D1%94%D1%81%D1%82%D1%80%D0%B0%D1%82%D0%BE%D1%80_%D1%80%D0%BE%D0%B7%D1%80%D0%B0%D1%85%D1%83%D0%BD%D0%BA%D0%BE%D0%B2%D0%B8%D1%85_%D0%BE%D0%BF%D0%B5%D1%80%D0%B0%D1%86%D1%96%D0%B9)). | `nvfjdjjfdjdkjf84iewjd` | :::warning ^7^ **Для фіскалізації чека необхідно:** 1. Партнер реєструється на ресурсі: checkbox.ua (з реєстрацією РРО та касира). 2. У кабінеті "checkbox" самостійно веде: відкриття/закриття зміни та звітність (X, Z). 3. У запиті через параметр `ticket` - Партнер передає інформацію Оператору для реєстрації фіскального чека. 4. На підставі даних запиту Оператор проводить перевірку відповідності суми операції із сумою товарів у чеку. 5. Оператор фіскалізує чек через ресурс: checkbox.ua. 6. В завершення - Оператор надсилає платнику (за погодженням) на email/sms посилання на чек РРО. **Для реєстрації чека необхідно:** 1. Передати Оператору логін/пароль касира, АБО 2. Формувати у кожному запиті підпис касира (`cashiersignature`). ::: Параметри масиву **"ticket"**: | Параметр | Обов’яз-ковість | Тип | Опис | Приклад | |:-:|:-:|:-:|-|:-:| | `ID` |Так|Рядок|Ідентифікатор товару.|`11`| | `Good` |Так|Рядок|Найменування товару.|`bolt`| | `Price` |Так| Ціле| Вартість товару в копійках. |1грн.=>`100`| | `Count` |Так| Ціле | Кількість товару. |1шт.=>`1000` 2.25кг=>`2250`| | `uktzed` |Ні|Рядок|Цифровий код товару згідно з [УКТ ЗЕД](https://uk.wikipedia.org/wiki/%D0%A3%D0%BA%D1%80%D0%B0%D1%97%D0%BD%D1%81%D1%8C%D0%BA%D0%B0_%D0%BA%D0%BB%D0%B0%D1%81%D0%B8%D1%84%D1%96%D0%BA%D0%B0%D1%86%D1%96%D1%8F_%D1%82%D0%BE%D0%B2%D0%B0%D1%80%D1%96%D0%B2_%D0%B7%D0%BE%D0%B2%D0%BD%D1%96%D1%88%D0%BD%D1%8C%D0%BE%D0%B5%D0%BA%D0%BE%D0%BD%D0%BE%D0%BC%D1%96%D1%87%D0%BD%D0%BE%D1%97_%D0%B4%D1%96%D1%8F%D0%BB%D1%8C%D0%BD%D0%BE%D1%81%D1%82%D1%96) (українська класифікація товарів зовнішньоекономічної діяльності).|`0403`| :::success <details> <summary>Приклад масиву даних "ticket"</summary> ~~~md { "ticket": [ { "ID": "11", "Good": "bolt", "Price": 100, "Count": 1000 }, { "ID": "22", "Good": "vtulka", "Price": 2500, "Count": 60000 } ] } ~~~ </details> ::: #### Параметри для криптопроєктів | Параметр | Обов’яз-ковість | Тип | Опис | Приклад | |:-:|:-:|:-:|-|:-:| | `AccountID` | Ні | Рядок | Номер криптовалютного гаманця клієнта / ID рахунку в платіжній системі / Номер рахунку онлайн банкінгу або біржі / ID грошового переказу / ID чека або ваучера. |`Jkf4j9LndJ4k520JkdnT52`| | `Signature` | Ні | Рядок | Сигнатура валюти, що купується – буквено-цифрове позначення валюти, яке складається зі скороченої назви валюти/криптовалюти/платіжної системи та ін. (“XPYUAH”, “LTC”, “NMC”, “XRP”...), згідно з [класифікацією сигнатур валют](https://jsons.info/signatures/currencies). |`XPYUAH`| | `Sum` | Ні | Рядок | Сума валюти операції обміну (кількість валюти, що купується). | `0.0025` | ### Приклад запиту :::success <details> <summary>Приклад структури "Data"</summary> ~~~md { "Account": "test@gmail.com", "Callback": { "PaySuccess": { "URL": "https://www.all4.shopping/payments/payment_success" } }, "CallBackURL": "https://www.all4.shopping/payments/xpay/callback", "Currency": "UAH", "Email": "mtest@gmail.com", "Exchange": "EUR", "FirstName": "Ім'я", "LastName": "Прізвище", "MiddleName": "", "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" } } ~~~ </details> ::: :::success <details> <summary>Приклад запиту [10005]</summary> ~~~md { "Partner": { "PartnerToken": "72a8ddb8-9145-4a41-af1a-8c48ecaa4be1", "OperationType": 10005, "Locale": "" }, "Data": "{\"PayType\": 7, \"Phone\": \"380507801058\", \"Account\": \"9ae56a0e-56b5-11ed-8c77-0050560147f8\", \"PaymentSum\: \"33000\", \"Callback\": {\"PaySuccess\": \"https://solutions.sportlife.ua/banking/success_ru.html\"}, \"Service\": [{\"ServiceCode\": \"SL_8\", \"Sum\": \"33000\", \"Attributes\": {\"ServiceName\": {\"uk\": \"Kyiv Teremky; Sports and health services; 000785051\"}}}], \"TTL\": 900, \"CallBackURL\": \"https://solutions.sportlife.ua/Connect/hs/paymentStatus/xPayStatus\", \"Transaction\": {\"TransactionID\": \"9ae56a0e-56b5-11ed-8c77-0050560147f8\", \"TerminalID\": \"1\"}}", "KeyAES": "", "Sign": "" } ~~~ </details> ::: ## Відповідь *Загальна інформація по формуванню структури відповіді наведена у розділі [“Загальна інформація по підключенню (API)”](https://hackmd.io/g3cItPVFStez0ql3Xj-2TA?both#%D0%A1%D1%82%D1%80%D1%83%D0%BA%D1%82%D1%83%D1%80%D0%B0-%D0%B2%D1%96%D0%B4%D0%BF%D0%BE%D0%B2%D1%96%D0%B4%D1%96).* ### Структура "Data" Успішна відповідь на запит [10005] містить посилання у вигляді рядка з ім'ям "URI" у структурі "Data": | Параметр | Обов’яз-ковість | Тип | Опис | Приклад | |:-:|:-:|:-:|-|:-:| | `URI` |Так| Рядок | Посилання на платіжну сторінку (Checkout). |`https://stage-mapi.xpay.com.ua/uk/frame/widget/bank-id/691fafc9-5d64-46b5-22ba-85ce61cc26be`| | `uuid` |Так| Рядок | Унікальний ідентифікатор, що зв'язує запити ["check"](https://hackmd.io/kk2x9Wx8QSe_vV11tA-KFA) та ["pay"](https://hackmd.io/2x_MsqZIT6epfiqcQimFwQ). |`f3cd72b6-e1ea-406f-9b44-a9b93b401b7f`| ### Приклади відповідей :::success <details> <summary>Операція проведена успішно</summary> ~~~md { "Code": 200, "Message": "done!", "Data": { "OperationDate": "2023-02-28T15:28:14.539768+02:00", "OperationID": 9490967, "OperationStatus": 10, "URI": "https://stage-mapi.xpay.com.ua/en/frame/widget/2cda0150-d6bc-4e21-9c96-f2210f20e56e", "uuid": "2cda0150-d6bc-4e21-9c96-f2210f20e56e" }, "KeyAES": "", "Sign": "" } ~~~ </details> ::: :::success <details> <summary>Помилка виконання операції</summary> ~~~md { "Code": 200, "Message": "done", "Data": { "OperationID": 111, "OperationStatus": 21, "Reason": 3 }, "KeyAES": "", "Sign": "" } ~~~ </details> ::: ## Тестові дані :::info ![](https://i.imgur.com/gtxKB22.png) Для тестування даного запиту застосовуйте параметри **Тестового Партнера**. Див. деталі підключення у розділі: ["Параметри підключення Тестового Партнера"](https://hackmd.io/kGejjgk0QaiwfpoZFnTadA). <details> <summary>Тестовий запит</summary> ~~~md { "Partner": { "PartnerToken": "72a8ddb8-9145-4a41-af1a-8c48ecaa4be1", "OperationType": 10005, "Locale": "UK" }, "Data": "{\"uuid\": \"c97c2b5a-5795-4eb1-b821-093bf86b241e\", \"Transaction\":{\"TransactionID\":\"8dвd1faa43331wwfff351\",\"TerminalID\": \"1\",\"DateTime\":\"20201211 120111\"},\"PayType\":\"0\",\"Phone\":\"380277777777\",\"Email\":\"volodymyr.testovych@gmail.com\",\"Account\":\"380277777777\",\"ClientIP\":\"89.68.252.11\",\"PanSuffix\":\"8888\",\"Currency\":\"UAH\",\"Exchange\":\"UAH\",\"Signature\":\"\",\"AccountID\":\"\",\"PaymentSum\":\"1000\",\"Sum\":\"1000\",\"FirstName\":\"Володимир\",\"LastName\":\"Зеленський\",\"MiddleName\":\"Олександрович\",\"BrowserFingerprint\":\"86a190af26de3a920c62ea19ba0df3a8\",\"RecipientCard\":{\"PAN\":\"8888888888888888\"},\"PaymentInfo\":[{\"Caption\":\"Призначення\",\"Value\":\"Оплатазапакети\"}],\"Service\":[{\"ServiceCode\":\"\",\"Sum\":\"\"}],\"Callback\":{\"PaySuccess\":{\"URL\":\"\"}},\"BillAttr\":{\"PayerAddress\":\"ВулицяПеремоги\"},\"TTL\":\"300\",\"CallBackURL\":\"https://partner.com/callback/xpay2\",\"AccountPayments\":[{\"Sum\":\"\",\"Purpose\":\"\",\"Account\":\"\",\"EDRPOU\":\"\",\"ID\":\"\",\"RecipientName\":\"\",\"SenderName\":\"\",\"IPN\":\"\"}],\"ticket\":[],\"Transaction\":{\"TransactionID\":\"8dвd1faa43331wwfff351\",\"TerminalID\":\"\",\"DateTime\":\"\"}}" } ~~~ </details> <details> <summary>Очікувана відповідь</summary> ~~~md { "Code": 200, "Message": "done!", "Data": { "OperationDate": "2023-02-28T15:28:14.539768+02:00", "OperationID": 9490967, "OperationStatus": 10, "URI": "https://stage-mapi.xpay.com.ua/en/frame/widget/2cda0150-d6bc-4e21-9c96-f2210f20e56e", "uuid": "2cda0150-d6bc-4e21-9c96-f2210f20e56e" }, "KeyAES": "", "Sign": "" } ~~~ </details> ::: ## Протокол двостадійної взаємодії Коли платіжна сторінка Партнера передбачає авторизацію клієнта (введення телефону/email), та у ході обробки даних на стороні Оператора виникає необхідність перевірки реквізитів оплати та/або уточнення суми оплати - застосовується протокол двостадійної взаємодії. Див. деталі у розділі: "[[check] Протокол двостадійної взаємодії](https://hackmd.io/kk2x9Wx8QSe_vV11tA-KFA)". ## Запити "pay/error/refund" (CallBackURL) Завершальним етапом у виконанні операції є надсилання нотифікацій Партнеру про **статус операції** у вигляді одного з запитів: * **"pay"** (оплата завершена), * **"error"** (помилка оплати), * **"refund"** (здійснено повернення). Див. деталі у розділі: "[[pay/error/refund] Статус операції (CallBackURL)](https://hackmd.io/2x_MsqZIT6epfiqcQimFwQ)". ## Отримання статусу операції Для перевірки поточного статусу операції застосовується запит: [[20003] "Отримання статусу операції"](https://hackmd.io/fvd8btZLQXywluia6w5uxg). Всі операції та статуси їх обробки доступні в особистому кабінеті Партнера, або в реєстрі оплат, отриманому на наступний день операції на пошту Партнера. Для запиту [10005] додатково реалізовано два стани обробки операції: - **Користувач ще не почав сплачувати** (`"Reason":100051`), - **Час очікування платежу сплинув** (`"Reason":100053`). | Код відповіді | Повідом-лення | Статус `OperationStatus` | Причина `Reason` | Стан оплати | |:-:|:-:|:-:|:-:|-| | `102` | `Processing` | `7` | 100051 | Користувач не почав оплату. | | `102` | `Processing` | `5` | будь-яка | Операція в обробці. | | `200` | `Error` | `21` | 100053 | Час очікування платежу сплинув. | | `200` | `Error` | `21` | будь-яка | Виникла помилка оплати. Див. опис у таблиці ["Коди причин відхилення операцій"](https://hackmd.io/aBE7H5cfQ-iqaN3SnwaQ-w#%D0%9A%D0%BE%D0%B4%D0%B8-%D0%BF%D1%80%D0%B8%D1%87%D0%B8%D0%BD-%D0%B2%D1%96%D0%B4%D1%85%D0%B8%D0%BB%D0%B5%D0%BD%D0%BD%D1%8F-%D0%BE%D0%BF%D0%B5%D1%80%D0%B0%D1%86%D1%96%D0%B9-%E2%80%9CReason%E2%80%9D:~:text=%D0%A2%D0%B0%D0%BA-,%D0%9A%D0%BE%D0%B4%D0%B8%20%D0%BF%D1%80%D0%B8%D1%87%D0%B8%D0%BD%20%D0%B2%D1%96%D0%B4%D1%85%D0%B8%D0%BB%D0%B5%D0%BD%D0%BD%D1%8F%20%D0%BE%D0%BF%D0%B5%D1%80%D0%B0%D1%86%D1%96%D0%B9%20%22Reason%22,-%22Reason%22). | | `200` | `Ok` | `10` | відсутня | Обробка операції завершена. | Див. деталі у розділі: ["Довідкові матеріали"](https://hackmd.io/aBE7H5cfQ-iqaN3SnwaQ-w). ## Пов'язані запити [[check] Протокол двостадійної взаємодії](https://hackmd.io/kk2x9Wx8QSe_vV11tA-KFA) [[pay/error/refund] Статус операції (CallBackURL)](https://hackmd.io/2x_MsqZIT6epfiqcQimFwQ) [[auth] Оплата методом "Google/Apple Pay"](https://hackmd.io/M0Q6tH0CTy-oPCA5QuFFig) [[20003] Отримання статусу операції](https://hackmd.io/fvd8btZLQXywluia6w5uxg) ## Довідкові матеріали Опис загальних параметрів системи XPAY див. у розділі ["Довідкові матеріали"](https://hackmd.io/aBE7H5cfQ-iqaN3SnwaQ-w): коди типів операцій, типи платіжних методів, коди статусів обробки операцій, відомості та помилки, що повертаються у відповіді та ін. ![](https://i.imgur.com/17gAyWb.png) :arrow_left: [На Головну](/Mj2ZqCVpSq6A6Jzm6ladlw) :arrow_left: [Загальна інформація по підключенню (API)](https://hackmd.io/g3cItPVFStez0ql3Xj-2TA) <details> <summary>Служба підтримки XPAY</summary> Телефон: +38 093 891 92 00 Email: info@xpay.com.ua Telegram: @xpaysupportbot </details>

Read more

[10301/10311/103013] Wallet-Card

MTBMoney System Integration

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

General API Integration Information