Прийом платежів з перенаправленням користувача на платіжну сторінку¶
Загальна схема взаємодії¶
-
Клієнт формує замовлення на сайті Мерчанта.
-
Щоб надати клієнту можливість вибору варіанта оплати, мерчант відправляє передзапит платежу і отримує у відповіді від платформи Payelata.com список доступних методів.
-
Мерчант відображає список методів і клієнт вибирає зручний йому спосіб оплатити замовлення.
Пункти 2 та 3 можна пропустити
Надсилання попереднього запиту не потрібно, якщо мерчант визначає метод оплати за клієнта і створює інвойс платежу після формування замовлення.
-
Мерчант створює інвойс платежу за допомогою публічного або приватного API. Отримавши інвойс Payelata.com:
- Ініціює транзакцію на стороні провайдера.
- Передає мерчанту дані для платіжної форми.
- Відправляє Callback мерчантові з повідомленням про успішне створення інвойсу.
-
Мерчант перенаправляє клієнта на сторінку платіжного провайдера з даними форми.
-
На сторінці провайдера клієнт запроваджує реквізити для оплати. Провайдер надсилає запит на списання коштів емітенту.
-
У випадку, якщо потрібен додатковий етап підтвердження платежу (верифікація 3DSecure або іншим способом), провайдер перенаправляє користувача на сторінку верифікації. Клієнт підтверджує платіж на сторінці верифікації, і дані передаються емітенту.
-
Емітент повертає результати оплати та завершує транзакцію.
-
Провайдер фіксує статус транзакції та повертає його платформі Payelata.com, а Payelata.com у свою чергу перенаправляє дані мерчанту.
-
Мерчант відображає клієнту статус платежу сторінках свого сайту.
-
Payelata.com відправляє мерчанту Callback із повідомленням про статус платежу.
-
Для уточнення статусу транзакції мерчанта може провести реконсиляцію платежу за ID або отримати повний список даних інвойсів за допомогою приватного API. Також на порталі є щоденне отримання звітів за транзакціями.
Передзапит платежу через публічний API¶
Передзапити використовуються для отримання списку доступних для цієї валюти послуг.
Передзапит не передбачає фільтрацію сервісів за ініційованою сумою, оскільки користувач може сплатити у валюті, відмінній від переданої.
API: PUBLIC
Авторизація: Public keys
Endpoint: /payment-prerequest
Method: POST
Приклади
{
"public_key":"pk_test_ClSQHi2T9WXuFa76WcwwBB6rspRpg6ANM69cS9zNOJy",
"currency":"USD"
}
{
"data": {
"currency": "USD",
"test_mode": true,
"services": {
"payment_card_usd_hpp": {
"code": "payment_card_usd_hpp",
"method": "payment_card",
"flow": "hpp",
"currency": "USD",
"fields": [],
"amount_min": 0.01,
"amount_max": 1000000
},
"test_usd_test": {
"code": "test_usd_test",
"method": "test",
"flow": "test",
"currency": "USD",
"fields": [
{
"key": "status",
"type": "string",
"label": {
"ru": "Статус",
"en": "Status",
"uk": "Статус"
},
"example": null,
"hint": {
"ru": "Введите статус",
"en": "Enter Status",
"uk": "Введіть статус"
},
"regexp": "^[a-zA-Z_]*$",
"required": true,
"position": 0
}
],
"amount_min": 0.01,
"amount_max": 9999999
}
},
"methods": {
"payment_card": {
"code": "payment_card",
"category": "payment_card",
"description": "",
"name": {
"en": "Payment card",
"ru": "Платежная карта",
"uk": "Платіжна карта"
},
"logo": "https://static.openfintech.io/payment_methods/payment_card/logo.svg",
"icon": "https://static.openfintech.io/payment_methods/payment_card/icon.svg",
"metadata": null,
"position": null,
"hide": null
},
"test": {
"code": "test",
"category": "alternative",
"description": "",
"name": {
"en": "Test",
"ru": "Тест",
"uk": "Тест"
},
"logo": "https://static.openfintech.io/payment_methods/test/logo.png",
"icon": "https://static.openfintech.io/payment_methods/test/icon.svg",
"metadata": null,
"position": null,
"hide": null
}
},
"account": {
"name": "4Docs",
"description": "4Docs only",
"icon": "https://static-dev.psp.name/images/default.svg?1595844446",
"website": null
}
}
}
Отримання списку доступних сервісів¶
Повний список сервісів¶
API: PRIVATE
Авторизація: BasicAuth
Endpoint: /payment-services
Method: GET
Приклад відповіді
{
"meta":{
"total":124,
"pages":7,
"page":1
},
"links":{
"first":"/api/payment-services?page[number]=1&page[size]=20",
"next":"/api/payment-services?page[number]=2&page[size]=20",
"last":"/api/payment-services?page[number]=7&page[size]=20"
},
"data":[
{
"type":"payment-services",
"id":"comcps_wQmYGz5RbkcgfdLI",
"attributes":{
"service":"test_xts_test",
"service_method":"test",
"service_currency":"XTS",
"available":true,
"active":false,
"enabled":true,
"amount_min":0.01,
"amount_max":9999999,
"fee_min":0,
"fee_max":0,
"fee_rate":0,
"fee_fix":0,
"reserve_lifetime":0,
"reserve_rate":0,
"currency":"GBP",
"test_mode":true
},
"relationships":{
"payment-method":{
"data":{
"type":"payment-methods",
"id":"test"
}
},
"payment-service":{
"data":{
"type":"payment-services",
"id":"test_xts_test"
}
}
},
"links":{
"self":"/api/payment-services/comcps_wQmYGz5RbkcgfdLI"
}
},
{
"type":"payment-services",
"id":"comcps_u1xxlHVw1NyeqmjJ",
"attributes":{
"service":"payment_card_usd_hpp",
"service_method":"payment_card",
"service_currency":"USD",
"available":true,
"active":false,
"enabled":true,
"amount_min":0.01,
"amount_max":1000000,
"fee_min":0,
"fee_max":0,
"fee_rate":0,
"fee_fix":0,
"reserve_lifetime":0,
"reserve_rate":0,
"currency":"GBP",
"test_mode": true
},
"relationships":{
"payment-method":{
"data":{
"type":"payment-methods",
"id":"payment_card"
}
},
"payment-service":{
"data":{
"type":"payment-services",
"id":"payment_card_usd_hpp"
}
}
},
"links":{
"self":"/api/payment-services/comcps_u1xxlHVw1NyeqmjJ"
}
},
{
"type":"payment-services",
"id":"comcps_TEKVfH0di0vGimkF",
"attributes":{
"service":"applepay_usd_hpp",
"service_method":"applepay",
"service_currency":"USD",
"available":true,
"active":false,
"enabled":true,
"amount_min":0.01,
"amount_max":1000000,
"fee_min":0,
"fee_max":0,
"fee_rate":0,
"fee_fix":0,
"reserve_lifetime":0,
"reserve_rate":0,
"currency":"GBP",
"test_mode": true
},
"relationships":{
"payment-method":{
"data":{
"type":"payment-methods",
"id":"applepay"
}
},
"payment-service":{
"data":{
"type":"payment-services",
"id":"applepay_usd_hpp"
}
}
},
"links":{
"self":"/api/payment-services/comcps_TEKVfH0di0vGimkF"
}
}
]
}
Дані сервісу за ID¶
API: PRIVATE
Авторизація: BasicAuth
Endpoint: /payment-services/{id}
Method: GET
Значення id: з попереднього запиту
Приклад відповіді
{
"data": {
"type": "payment-services",
"id": "comcps_u1xxlHVw1NyeqmjJ",
"attributes": {
"service": "payment_card_usd_hpp",
"service_method": "payment_card",
"service_currency": "USD",
"available": true,
"active": false,
"enabled": true,
"amount_min": 0.01,
"amount_max": 1000000,
"fee_min": 0,
"fee_max": 0,
"fee_rate": 0,
"fee_fix": 0,
"reserve_lifetime": 0,
"reserve_rate": 0,
"currency": "GBP",
"test_mode": true
},
"relationships": {
"payment-method": {
"data": {
"type": "payment-methods",
"id": "payment_card"
}
},
"payment-service": {
"data": {
"type": "payment-services",
"id": "payment_card_usd_hpp"
}
}
},
"links": {
"self": "/api/payment-services/comcps_u1xxlHVw1NyeqmjJ"
}
}
}
Ініціювання інвойсу¶
Через публічний API¶
Attention
Публічний API підтримує ініціювання інвойсів, якщо в налаштуваннях акаунту для платежів вимкнено параметр "Тільки приватний API" (Forbid public access: FALSE).
Налаштування → Опції платежів
API: PUBLIC
Авторизація: Public keys
Endpoint: /payment-invoices
Method: POST
Обов'язкові поля запиту:
public_key- * публічний ключ акаунту *reference_id- унікальний ідентифікатор операції на стороні мерчантаservice- ідентифікатор сервісу, наприкладpayment_card_usd_hpp. Список усіх доступних сервісів можна переглянути в налаштуваннях платежівcurrency- валюта платежуamount- сума у float форматі, наприклад100.55
Додаткове поле: - description
Приклади (JSON)
{
"public_key": "pk_test_ClSQHi2T9WXuFa76WcwwBB6rspRpg6ANM69cS9zNOJy",
"reference_id": "7135b08b-701b-4fbc-a7d2-b2763d96d415",
"description": "Invoice Example",
"service": "payment_card_usd_hpp",
"currency": "USD",
"amount": 123.45
}
{
"data": {
"id": "cpi_QGcJxoBxnYStkuvN",
"serial_number": "QGcJxoBxnYStkuvN",
"created": 1595846278,
"test_mode": true,
"reference_id": "7135b08b-701b-4fbc-a7d2-b2763d96d415",
"currency": "USD",
"amount": 123.45,
"payment_amount": 123.45,
"processed_amount": null,
"refunded_amount": null,
"description": "Invoice Example",
"has_return_url": false,
"status": "process_pending",
"resolution": "OK",
"service": "payment_card_usd_hpp",
"service_method": "payment_card",
"service_flow": "hpp",
"service_currency": "USD",
"metadata": {
"merchant_url": "https://lets.doc.it"
},
"hpp_url": "https://pay.psp.name/redirect/hpp/?cpi=cpi_Y8Puis4vtNjAYZwb",
"active_payment": {
"payload": {
"action": "https://cardgate-staging.psp.name/hpp/cgi_8z1WIRwAtwvyI3G9",
"method": "GET",
"params": [],
"metadata": {
"sid": "cgi_8z1WIRwAtwvyI3G9",
"token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzUxMiJ9.eyJzaWQiOiJjZ2lfOHoxV0lSd0F0d3Z5STNHOSIsImV4cCI6MTU5NTg0ODA3OH0.NZE80zZm6-L8B8Q38xING5vXS86tCryGoyIefq9Aju-pCSmk8Sq1gKvCfFxTmDeytv4J509JEuSg4Ti0TK2ZeTLTvNsDU-wqWJqxL9sUq6Hd-1-2qK60qbtFJ7NbqwGFUaRpe8lU3QKM4F1S7JcTmqXg-Iz9dsVNr9obNj9Pw2MGndInKGWk2qG-ZQRZV0IXRrk49xSLo24wtLYPaZRGEkY1rPmmrSeeO1AFigfDLyld7A3w13EzotPwWPtsoPZFA4Rhcggr1s8Fjnl8iZJk8MBhHWZ4xQjdI1TNAzd1w-s6mfWjAzJlrjXge59X7NI4nuVaUroOg-o63sCCSFNTZfcP-HHMcrw01UG1COyxV4DXogrzSGuLFubqEa67BMgQGdB_pRK_NMqMJyFXTGLzG-A8m0AtIfmh45zUJeSK5Xgjc-luSh0mJAthQt0II2sBKJ_iJXl6ZWWffJIdzuIqmPWrjdw8EK2yCvTZtXl7xD4Rj37PaoQ1-4ezn_rnXk"
}
},
"status": "invoked",
"resolution": "OK"
}
}
}
Note
Для перенаправлення користувача на сторінку оплати необхідно використати hpp_url: пренеправити користувача на вказаний URL (метод GET).
Через приватний API¶
API: PRIVATE
Авторизация: BasicAuth
Endpoint: /payment-invoices
Method: POST
Обов'язкові поля:
reference_id- унікальний ідентифікатор операції на стороні мерчантаservice- ідентифікатор сервісу, наприкладpayment_card_usd_hpp. Список усіх доступних сервісів можна подивитися в особистому кабінеті або отримати відповідь на запитcurrency- валюта платежуamount- сума у float форматі, наприклад100.55
Додаткові поля:
flow- * визначає тип інвойсу. Може приймати значення:charge,verify. У разі відсутності параметра у запиті за замовчуванням приймається значенняcharge*service_fields- обов'язковий параметр у деяких сервісах, які вимагають передачі реквізитів, наприклад платіж QIWI-гаманцем передбачає обов'язковий атрибутномера телефонуабоідентифікатор гаманця
Наприклад, qiwi_usd_hpp
"service_fields": {
"phone": "+380987654321"
}
test_mode- ознака тестової / "бойової" операції. Може приймати значенняtrue,false. У разі відсутності параметра у запиті за замовчуванням приймається значенняfalsedescriptioncustomerreference_idобов'язковий атрибут за наявності об'єкта у запитіnameemailphonemetadata
metadatareturn_url- універсальний URL для повернення користувача після оплатиreturn_urls- спеціальний об'єкт із 3-ма варіантами URL для повернення користувача на підставі статусу платежуsuccessfailpendingобов'язковий атрибут за наявності об'єкта у запиті
callback_url- URL для надсилання повідомлень Callbacks при зміні статусу операціїgateway_options- опції модифікації шлюзу, наприклад - для видозміни платіжної сторінки (необхідно уточнювати набір та можливі значення для кожного конкретного акаунту)expires- дата та час закінчення терміну дії інвойсу у форматі DateTime; можливий для встановлення термін дії інвойсу при цьому – від 14 хвилин до 2 діб від дати створення
Приклади (JSON)
{
"data":{
"type":"payment-invoices",
"attributes":{
"reference_id":"a30ebec4-035c-4fc5-8c48-b525ca601f37",
"amount":100,
"currency":"USD",
"service":"payment_card_usd_hpp",
"flow":"charge",
"test_mode":true,
"description":"Invoice Example",
"gateway_options":{
"cardgate":{
"tokenize":false
}
},
"customer":{
"reference_id":"1203515",
"email":"somename@domain.com",
"name":"John Wick",
"phone":"+380987654321",
"metadata":{
"key1":"value1",
"key2":"value2"
}
},
"metadata":{
"key":"value"
},
"return_url":"https://example.com",
"return_urls": {
"success":"https://example.com/1",
"pending":"https://example.com/2",
"fail":"https://example.com/3"
},
"callback_url":"https://example.com",
"expires": "2020-12-13T15:52:00+00:00"
}
}
}
{
"data": {
"type": "payment-invoices",
"id": "cpi_HeSWMM9LvQonCcQc",
"attributes": {
"serial_number": "HeSWMM9LvQonCcQc",
"status": "process_pending",
"resolution": "ok",
"moderation_required": false,
"amount": 100,
"payment_amount": 100,
"currency": "USD",
"service_currency": "USD",
"reference_id": "70d42236-2cc4-4e26-8f2f-987fd8fbc276",
"test_mode": true,
"fee": 0,
"deposit": 100,
"processed": null,
"processed_amount": null,
"refunded_amount": null,
"processed_fee": null,
"processed_deposit": null,
"metadata": {
"key": "value",
"merchant_url": "https://lets.doc.it"
},
"flow_data": {
"action": "https://cardgate-staging.psp.name/hpp/cgi_G0bsyhroZj802zQU",
"method": "GET",
"params": [],
"metadata": {
"sid": "cgi_G0bsyhroZj802zQU",
"token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzUxMiJ9.eyJzaWQiOiJjZ2lfRzBic3locm9aajgwMnpRVSIsImV4cCI6MTU5NzgzNDg5OH0.Vsjj8tcnKqFrxz5SynNdC0q8x_eQawJG9CJTAEUNm6JQG64En4zYij_DjggdWOlpKLy2n-pUSLcacp6wNsF6rF7G4GrcKJ37yQVUXyaXrnLyJ7ObgNgSRWOk2R0z_DKpVMXxM12p4NXlU1B6Oz8zc72G1gJIApxkMa1bKsfG-zubPZuYK_3wRHBClibmRgbpbVzGTYcBNDdbreaeMW0LdRKUI_LDqJQdf5y29tJMFPXogZNs7rvXQPlV8d9mc8i0aaO1kwIFiBiexVEoCObnyopadrRuKyorU2bBVYAXbrYHwFP18hZAkm-H3P5mUqt8q1-yXYZF0qk4Gd_hAn-ePN101jnIjj-7L0VmO8ZU1oiGCswsNAmO_IKT7j7c4PG2wSFnHLwYR5bxvPKEDh5NmW6DZlPtL4BsdeW-Z1z93hIw923BWfVCldKvL_E4KYNYa9Wcu-D3e3wMSWvfph_-UsmbIJeQeqQEX3Mz2s78Y98ETAQFLqocZBAqZtGQ-UVYMXZlu6-_LI5REVlvW0REuV04zdPXiDWoxu_Fr-G4XqkBusryxhMvSqmu_CCTCrSnRV2Veu8jHTsUMFBoQ3gIhOz6DRT9N1LhbJv4_0L6Vjw6zGpfSMOeEyCD34IInuhUyAUYU-PQkxYHyqCYXPPSqxJVDl5Bia1OFDHITu4rU4A"
}
},
"flow": "hpp",
"hpp_url": "https://pay.psp.name/redirect/hpp/?cpi=cpi_Y8Puis4vtNjAYZwb",
"payment_flow": "charge",
"created": 1597833098,
"updated": 1597833098,
"payload": null,
"description": "Invoice Example",
"descriptor": null,
"callback_url": "https://example.com",
"return_url": "https://example.com",
"original_data": {
"external_id": null,
"merchant_id": null,
"provider_id": null,
"external_mid": "org_02HJ5jTUtan8ZXaT",
"provider_code": null
},
"rrn": null,
"approval_code": null,
"reserved_amount": null,
"reserve_expires": null,
"unreserved": null,
"source": "merchant_api",
"callback_logs": []
},
"relationships": {
"payment-service": {
"data": {
"type": "payment-services",
"id": "payment_card_usd_hpp"
}
},
"payment-method": {
"data": {
"type": "payment-methods",
"id": "payment_card"
}
},
"customer": {
"data": {
"type": "customers",
"id": "cus_Tjhe1ufEB3kRrgWy"
}
}
},
"links": {
"self": "/api/payment-invoices/cpi_HeSWMM9LvQonCcQc"
}
}
}
Note
Є 2 основні варіанти перенаправлення користувача на сторінку оплати:
-
Використати
flow_dataдля формування html форми: action форми =>action, method форми =>methodприховані параметри форми =>params(якщо є у відповіді). -
Використати
hpp_url: перенаправити користувача на вказаний URL (метод GET).
Реконсиляція платежу (за ID)¶
Note
Статуси інвойсів описані в Посібниках. Коди стану HTTP, які використовуються API у відповідях на запити, описані нижче.
Через публічний API¶
API: PUBLIC
Авторизація: Public keys
Endpoint: /payment-invoices/{id}
Method: GET
Приклад відповіді (JSON)
{
"data": {
"id": "cpi_HeSWMM9LvQonCcQc",
"serial_number": "HeSWMM9LvQonCcQc",
"created": 1597833098,
"test_mode": true,
"reference_id": "70d42236-2cc4-4e26-8f2f-987fd8fbc276",
"currency": "USD",
"amount": 100,
"payment_amount": 100,
"processed_amount": 100,
"refunded_amount": null,
"description": "Invoice Example",
"has_return_url": true,
"status": "processed",
"resolution": "OK",
"service": "payment_card_usd_hpp",
"service_method": "payment_card",
"service_flow": "hpp",
"service_currency": "USD",
"metadata": {
"key": "value",
"merchant_url": "https://lets.doc.it"
},
"active_payment": {
"payload": {
"action": "https://cardgate-staging.psp.name/hpp/cgi_G0bsyhroZj802zQU",
"method": "GET",
"params": [],
"metadata": {
"sid": "cgi_G0bsyhroZj802zQU",
"token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzUxMiJ9.eyJzaWQiOiJjZ2lfRzBic3locm9aajgwMnpRVSIsImV4cCI6MTU5NzgzNDg5OH0.Vsjj8tcnKqFrxz5SynNdC0q8x_eQawJG9CJTAEUNm6JQG64En4zYij_DjggdWOlpKLy2n-pUSLcacp6wNsF6rF7G4GrcKJ37yQVUXyaXrnLyJ7ObgNgSRWOk2R0z_DKpVMXxM12p4NXlU1B6Oz8zc72G1gJIApxkMa1bKsfG-zubPZuYK_3wRHBClibmRgbpbVzGTYcBNDdbreaeMW0LdRKUI_LDqJQdf5y29tJMFPXogZNs7rvXQPlV8d9mc8i0aaO1kwIFiBiexVEoCObnyopadrRuKyorU2bBVYAXbrYHwFP18hZAkm-H3P5mUqt8q1-yXYZF0qk4Gd_hAn-ePN101jnIjj-7L0VmO8ZU1oiGCswsNAmO_IKT7j7c4PG2wSFnHLwYR5bxvPKEDh5NmW6DZlPtL4BsdeW-Z1z93hIw923BWfVCldKvL_E4KYNYa9Wcu-D3e3wMSWvfph_-UsmbIJeQeqQEX3Mz2s78Y98ETAQFLqocZBAqZtGQ-UVYMXZlu6-_LI5REVlvW0REuV04zdPXiDWoxu_Fr-G4XqkBusryxhMvSqmu_CCTCrSnRV2Veu8jHTsUMFBoQ3gIhOz6DRT9N1LhbJv4_0L6Vjw6zGpfSMOeEyCD34IInuhUyAUYU-PQkxYHyqCYXPPSqxJVDl5Bia1OFDHITu4rU4A"
}
},
"status": "processed",
"resolution": "OK"
}
}
}
Через приватний API¶
API: PRIVATE
Авторизація: BasicAuth
Endpoint:
/payment-invoices/{id}— для перевірки за ідентифікатором інвойсу/payment-invoices?filter[reference_id]={reference_id}— для перевірки за ідентифікатором замовлення мерчанта (reference_id)
Method: GET
Приклад відповіді (JSON)
{
"data": {
"type": "payment-invoices",
"id": "cpi_HeSWMM9LvQonCcQc",
"attributes": {
"serial_number": "HeSWMM9LvQonCcQc",
"status": "processed",
"resolution": "ok",
"moderation_required": false,
"amount": 100,
"payment_amount": 100,
"currency": "USD",
"service_currency": "USD",
"reference_id": "70d42236-2cc4-4e26-8f2f-987fd8fbc276",
"test_mode": true,
"fee": 0,
"deposit": 100,
"processed": 1597833205,
"processed_amount": 100,
"refunded_amount": null,
"processed_fee": 0,
"processed_deposit": 100,
"metadata": {
"key": "value",
"merchant_url": "https://lets.doc.it"
},
"flow_data": {
"action": "https://cardgate-staging.psp.name/hpp/cgi_G0bsyhroZj802zQU",
"method": "GET",
"params": [],
"metadata": {
"sid": "cgi_G0bsyhroZj802zQU",
"token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzUxMiJ9.eyJzaWQiOiJjZ2lfRzBic3locm9aajgwMnpRVSIsImV4cCI6MTU5NzgzNDg5OH0.Vsjj8tcnKqFrxz5SynNdC0q8x_eQawJG9CJTAEUNm6JQG64En4zYij_DjggdWOlpKLy2n-pUSLcacp6wNsF6rF7G4GrcKJ37yQVUXyaXrnLyJ7ObgNgSRWOk2R0z_DKpVMXxM12p4NXlU1B6Oz8zc72G1gJIApxkMa1bKsfG-zubPZuYK_3wRHBClibmRgbpbVzGTYcBNDdbreaeMW0LdRKUI_LDqJQdf5y29tJMFPXogZNs7rvXQPlV8d9mc8i0aaO1kwIFiBiexVEoCObnyopadrRuKyorU2bBVYAXbrYHwFP18hZAkm-H3P5mUqt8q1-yXYZF0qk4Gd_hAn-ePN101jnIjj-7L0VmO8ZU1oiGCswsNAmO_IKT7j7c4PG2wSFnHLwYR5bxvPKEDh5NmW6DZlPtL4BsdeW-Z1z93hIw923BWfVCldKvL_E4KYNYa9Wcu-D3e3wMSWvfph_-UsmbIJeQeqQEX3Mz2s78Y98ETAQFLqocZBAqZtGQ-UVYMXZlu6-_LI5REVlvW0REuV04zdPXiDWoxu_Fr-G4XqkBusryxhMvSqmu_CCTCrSnRV2Veu8jHTsUMFBoQ3gIhOz6DRT9N1LhbJv4_0L6Vjw6zGpfSMOeEyCD34IInuhUyAUYU-PQkxYHyqCYXPPSqxJVDl5Bia1OFDHITu4rU4A"
}
},
"flow": "hpp",
"payment_flow": "charge",
"created": 1597833098,
"updated": 1597833207,
"payload": {
"token": null,
"client_ip": "",
"payment_card": {
"last": "0000",
"mask": "512381******0000",
"brand": "mastercard",
"first": "512381",
"holder": null,
"network": "mastercard",
"expiry_year": "24",
"issuer_name": "FIRST DATA CORPORATION",
"expiry_month": "12",
"issuer_country": "US"
}
},
"description": "Invoice Example",
"descriptor": null,
"callback_url": "https://example.com",
"return_url": "https://example.com",
"original_data": {
"external_id": "cgi_8A8vc28Hr15D8tZ3",
"merchant_id": "host2hostTest",
"provider_id": null,
"external_mid": "org_02HJ5jTUtan8ZXaT",
"provider_code": "test"
},
"rrn": null,
"approval_code": null,
"reserved_amount": null,
"reserve_expires": null,
"unreserved": null,
"source": "merchant_api",
"callback_logs": {
"1597833098": {
"status": "done",
"processed": 1597833099,
"response_code": 200,
"transaction_status": "process_pending"
},
"1597833206": {
"status": "done",
"processed": 1597833207,
"response_code": 200,
"transaction_status": "processed"
}
}
},
"relationships": {
"payment-service": {
"data": {
"type": "payment-services",
"id": "payment_card_usd_hpp"
}
},
"payment-method": {
"data": {
"type": "payment-methods",
"id": "payment_card"
}
},
"customer": {
"data": {
"type": "customers",
"id": "cus_Tjhe1ufEB3kRrgWy"
}
}
},
"links": {
"self": "/api/payment-invoices/cpi_HeSWMM9LvQonCcQc"
}
}
}
Отримати повний список інвойсів (через приватний API)¶
API: PRIVATE
Авторизація: BasicAuth
Endpoint: /payment-invoices
Method: GET
Приклад відповіді (JSON)
{
"meta": {
"count": 17,
"size": 20,
"before": "cpi_o8CBGwATmJag4p32",
"after": "cpi_HeSWMM9LvQonCcQc"
},
"links": {
"prev": "",
"next": ""
},
"data": [
{
"type": "payment-invoices",
"id": "cpi_HeSWMM9LvQonCcQc",
"attributes": {
"serial_number": "HeSWMM9LvQonCcQc",
"status": "processed",
"resolution": "ok",
"moderation_required": false,
"amount": 100,
"payment_amount": 100,
"currency": "USD",
"service_currency": "USD",
"reference_id": "70d42236-2cc4-4e26-8f2f-987fd8fbc276",
"test_mode": true,
"fee": 0,
"deposit": 100,
"processed": 1597833205,
"processed_amount": 100,
"refunded_amount": null,
"processed_fee": 0,
"processed_deposit": 100,
"metadata": {
"key": "value",
"merchant_url": "https://lets.doc.it"
},
"flow_data": {
"action": "https://cardgate-staging.psp.name/hpp/cgi_G0bsyhroZj802zQU",
"method": "GET",
"params": [],
"metadata": {
"sid": "cgi_G0bsyhroZj802zQU",
"token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzUxMiJ9.eyJzaWQiOiJjZ2lfRzBic3locm9aajgwMnpRVSIsImV4cCI6MTU5NzgzNDg5OH0.Vsjj8tcnKqFrxz5SynNdC0q8x_eQawJG9CJTAEUNm6JQG64En4zYij_DjggdWOlpKLy2n-pUSLcacp6wNsF6rF7G4GrcKJ37yQVUXyaXrnLyJ7ObgNgSRWOk2R0z_DKpVMXxM12p4NXlU1B6Oz8zc72G1gJIApxkMa1bKsfG-zubPZuYK_3wRHBClibmRgbpbVzGTYcBNDdbreaeMW0LdRKUI_LDqJQdf5y29tJMFPXogZNs7rvXQPlV8d9mc8i0aaO1kwIFiBiexVEoCObnyopadrRuKyorU2bBVYAXbrYHwFP18hZAkm-H3P5mUqt8q1-yXYZF0qk4Gd_hAn-ePN101jnIjj-7L0VmO8ZU1oiGCswsNAmO_IKT7j7c4PG2wSFnHLwYR5bxvPKEDh5NmW6DZlPtL4BsdeW-Z1z93hIw923BWfVCldKvL_E4KYNYa9Wcu-D3e3wMSWvfph_-UsmbIJeQeqQEX3Mz2s78Y98ETAQFLqocZBAqZtGQ-UVYMXZlu6-_LI5REVlvW0REuV04zdPXiDWoxu_Fr-G4XqkBusryxhMvSqmu_CCTCrSnRV2Veu8jHTsUMFBoQ3gIhOz6DRT9N1LhbJv4_0L6Vjw6zGpfSMOeEyCD34IInuhUyAUYU-PQkxYHyqCYXPPSqxJVDl5Bia1OFDHITu4rU4A"
}
},
"flow": "hpp",
"payment_flow": "charge",
"created": 1597833098,
"updated": 1597833207,
"payload": {
"token": null,
"client_ip": "",
"payment_card": {
"last": "0000",
"mask": "512381******0000",
"brand": "mastercard",
"first": "512381",
"holder": null,
"network": "mastercard",
"expiry_year": "24",
"issuer_name": "FIRST DATA CORPORATION",
"expiry_month": "12",
"issuer_country": "US"
}
},
"description": "Invoice Example",
"descriptor": null,
"callback_url": "https://example.com",
"return_url": "https://example.com",
"original_data": {
"external_id": "cgi_G0bsyhroZj802zQU",
"merchant_id": "host2hostTest",
"provider_id": null,
"external_mid": "ma_aBctkJ3WiRndih0m",
"provider_code": "test"
},
"rrn": null,
"approval_code": null,
"reserved_amount": null,
"reserve_expires": null,
"unreserved": null,
"source": "merchant_api",
"callback_logs": {
"1597833098": {
"status": "done",
"processed": 1597833099,
"response_code": 200,
"transaction_status": "process_pending"
},
"1597833206": {
"status": "done",
"processed": 1597833207,
"response_code": 200,
"transaction_status": "processed"
}
}
},
"relationships": {
"payment-service": {
"data": {
"type": "payment-services",
"id": "payment_card_usd_hpp"
}
},
"payment-method": {
"data": {
"type": "payment-methods",
"id": "payment_card"
}
},
"customer": {
"data": {
"type": "customers",
"id": "cus_Tjhe1ufEB3kRrgWy"
}
}
},
"links": {
"self": "/api/payment-invoices/cpi_HeSWMM9LvQonCcQc"
}
},
{
"type": "payment-invoices",
"id": "cpi_Qtg8wyWcnSYLksFh",
"attributes": {
"serial_number": "Qtg8wyWcnSYLksFh",
"status": "process_failed",
"resolution": "expired",
"moderation_required": false,
"amount": 100,
"payment_amount": 100,
"currency": "USD",
"service_currency": "USD",
"reference_id": "05233537-7b5c-4cb8-b596-d65ec9671c67",
"test_mode": true,
"fee": 0,
"deposit": 100,
"processed": null,
"processed_amount": null,
"refunded_amount": null,
"processed_fee": null,
"processed_deposit": null,
"metadata": {
"key": "value",
"merchant_url": "https://lets.doc.it"
},
"flow_data": {
"action": "https://cardgate-staging.psp.name/hpp/cgi_jYwKJcItnDjnYzZj",
"method": "GET",
"params": [],
"metadata": {
"sid": "cgi_jYwKJcItnDjnYzZj",
"token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzUxMiJ9.eyJzaWQiOiJjZ2lfall3S0pjSXRuRGpuWXpaaiIsImV4cCI6MTU5NzQxODU2Mn0.y9oVZZx9KKdelCNxtY3U9hhWK0R6LIZrQI0w6GvTZamnwU5c1CAJqBydhEQ1v2o5kmrklUZFSlBFjTlKAy3LBUElW4pfZfaEpixgGC7NEtXkYK8lKYJ8cYLJl-S3s2ONcH5_Nhfu5FGdY0iTa8_giLNUgUZxMGnWY6hy29pexBaYr335I7L-lhqAzwhfY-KJH6KpYGOe_-rJgR447TEdABptqlOExGdAk9lS9PS77aJwIodOV1__xbbu0PRPW__L1S06WfDBfUUoaMulbn9-GyyUNbLs-qoADl_amrkxA0qWfs6ylyOAgsARlVUPs-gh2wVtqxHilPdflXZgfPVi9i9UphiquoGQIObOXJqm5CfuStvWxLNVDIOqcx9wbbXWt9i67W0quzVteQUpCDM0EVMR0WZ-j24JEnz2sllD_Lcz0cA22hZXH2b05tPCl30OwTWX0jkBy5ZzzLVYtQnWn-OPaOPoisK9tRdouDGk1UoTvmAJh_RUin1-wXWq9Zv2VXs6XamjR1sIEbj2Vd5IagCmiKyQiLwG7Jek_lbtF-N5e9JzBeAngf-k6UmA-q6RDS-EMdryH2_qfNF3szxUHq-Yz-LVtanxq263DeA7N8ytJGspZq6MzVsMiixPAyZoVf92M0T6rnYYh23hTdJzxzGBVcov_lOb05XCAHpkG4M"
}
},
"flow": "hpp",
"payment_flow": "charge",
"created": 1597416762,
"updated": 1597418667,
"payload": null,
"description": "Invoice Example",
"descriptor": null,
"callback_url": "https://example.com",
"return_url": "https://example.com",
"original_data": {
"external_id": null,
"merchant_id": null,
"provider_id": null,
"external_mid": "org_02Utan8ZXaTHJ5jT",
"provider_code": null
},
"rrn": null,
"approval_code": null,
"reserved_amount": null,
"reserve_expires": null,
"unreserved": null,
"source": "merchant_api",
"callback_logs": {
"1597416763": {
"status": "done",
"processed": 1597416763,
"response_code": 200,
"transaction_status": "process_pending"
},
"1597418666": {
"status": "done",
"processed": 1597418667,
"response_code": 200,
"transaction_status": "process_failed"
}
}
},
"relationships": {
"payment-service": {
"data": {
"type": "payment-services",
"id": "payment_card_usd_hpp"
}
},
"payment-method": {
"data": {
"type": "payment-methods",
"id": "payment_card"
}
},
"customer": {
"data": {
"type": "customers",
"id": "cus_Tjhe1ufEB3kRrgWy"
}
}
},
"links": {
"self": "/api/payment-invoices/cpi_Qtg8wyWcnSYLksFh"
}
}
]
}
Коди стану HTTP, що використовуються у відповідях¶
Приклади відповідей із кодами та описами помилок
{
"errors": [
{
"status": "Unauthorized",
"code": "401"
}
]
}
{
"errors": [
{
"status": "Not Found",
"code": "404"
}
]
}
{
"errors": [
{
"status": "Method Not Allowed",
"code": "405"
}
]
}
{
"errors": {
"amount": "This value should be greater than 0."
}
}
{
"errors": [
{
"status": "internal_error",
"code": "500",
"title": "internal_error",
"detail": "Internal server error."
}
]
}
2xx Успішні¶
| Код | Опис |
|---|---|
200 OK | Запит виконаний успішно |
201 Created | POST запит на "створення інвойса" виконаний успішно |
4xx Помилки на стороні клієнта¶
| Код | Тип | Опис | Інструкції |
|---|---|---|---|
400 Bad Request | Транспортні | Запит невалідної структури сервер не може його обробити | Необхідно запитати статус операції (якщо використано правильний метод, але на запит статусу отримано 404 помилки, можна вважати запит неуспішним і повторити операцію) |
401 Unauthorized | Авторизації | Для отримання запиту потрібна аутентифікація | Перевірити дані авторизації. Запит фінально невдалий. Операція не створилася за платформи (якщо помилка виникла при створенні, не за інших методах) |
403 Forbidden | Авторизації | У клієнта немає прав доступу виклик методу | Перевірити дані авторизації. Запит фінально невдалий. Операція не створилася за платформи (якщо помилка виникла при створенні, не за інших методах) |
404 Not Found | Валідації | Сервер неспроможна знайти запитуваний метод чи ресурс | У запиті зазначено некоректний метод чи операції немає (при коректному запиті статусу) |
405 Method Not Allowed | Валідації | Метод відправки запиту може бути використаний | Запит фінально неуспешный. Операція не створилася за платформи (якщо помилка виникла при створенні, не за інших методах) |
409 Conflict | Валідації | Сутність із таким ідентифікатором вже існує. У відповіді повернеться код і повідомлення помилки, в тілі повернуться дані існуючої операції | |
422 Unprocessable Entity | Валідації | Сервер не може прийняти запит (некоректні дані або налаштування акаунту) | Запит фінально неуспішний. Операція не створилася за платформи (якщо помилка виникла при створенні, не за інших методах) |
5xx Помилки на стороні сервера¶
| Код | Опис | Інструкції |
|---|---|---|
500 Internal Server Error | Внутрішня помилка сервера. Не гарантує помилки створення операції. | Необхідно запросити статус операції. У разі відсутності операції на сервері можна викликати метод створення |
502 Bad Gateway | Проблема обробки запиту. Визначено недійсний шлюз. Не гарантує помилки створення операції. | Необхідно запросити статус операції. У разі відсутності операції на сервері можна викликати метод створення |
503 Service Unavailable | Сервер недоступний зараз. Не гарантує помилку створення операції. Необхідно запросити статус операції. У разі відсутності операції на сервері можна викликати метод створення | |
504 Gateway Timeout | Сервер не зміг повернути відповідь за певний проміжок часу. Не гарантує помилку створення операції. | Необхідно запитати статус операції. У разі відсутності операції на сервері можна викликати метод створення |
Warning
Якщо створення операції пройшло успішно, а на будь-який інший запит отримано відповідь з 4XX або 5XX HTTP кодом, необхідно уточнювати статус методом реконсиляції або через канали комунікації технічної підтримки.
Note
При використанні Callback методу оповіщення — при отриманні помилок необхідно дочекатися Callback або викликати метод запиту статусу для уточнення стану операції