Прийом платежів з перенаправленням користувача на платіжну сторінку¶

Загальна схема взаємодії¶

Клієнт формує замовлення на сайті мерчанта.
Щоб надати клієнту можливість вибору варіанту оплати, мерчант відправляє попередній запит платежу і отримує у відповіді від платформи CASCAD список доступних методів.
Мерчант відображає список методів, а клієнт обирає зручний для нього спосіб оплатити замовлення.

Пункти 2 та 3 можна пропустити

Надсилання попереднього запиту не потрібно, якщо мерчант визначає метод оплати за клієнта і створює інвойс платежу після формування замовлення.
Мерчант створює інвойс платежу з допомогою публічного або приватного API. Отримавши інвойс, CASCAD:
- Ініціює транзакцію на боці провайдера.
- Передає мерчантові дані для платіжної форми.
- Відправляє Callback мерчанту з повідомленням про успішне створення інвойсу.
Мерчант перенаправляє клієнта на сторінку платіжного провайдера з даними форми.
На сторінці провайдера клієнт вводить реквізити для оплати. Провайдер надсилає запит на списання коштів емітенту.
У випадку, якщо потрібен додатковий етап підтвердження платежу (верифікація 3DSecure або іншим способом), провайдер перенаправляє користувача на сторінку верифікації. Клієнт підтверджує платіж на сторінці верифікації і дані передаються емітенту.
Емітент повертає результати оплати та завершує транзакцію.
Провайдер фіксує статус транзакції та повертає його платформі CASCAD, а CASCAD у свою чергу перенаправляє дані мерчантові.
Мерчант відображає клієнтові статус платежу на сторінках свого сайту.
CASCAD відправляє мерчанту Callback з повідомленням про статус платежу.
Для уточнення статусу транзакції мерчанта може провести реконсиляцію платежу за ID або отримати повний список даних інвойсів з допомогою приватного API. Також на порталі доступне щоденне отримання звітів за транзакціями.

Передзапит платежу через публічний API¶

Передзапити використовуються для отримання списку доступних для цієї валюти сервісів.

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

API: PUBLIC

Авторизація: Public keys

Endpoint: /payment-prerequest

Method: POST

Приклади

Запит

{
"public_key":"pk_test_ClSQHi2T9WXuFa76WcwwBB6rspRpg6ANM69cS9zNOJy",
"currency":"UAH"
}

Відповідь

{
    "data": {
        "currency": "UAH",
        "test_mode": true,
        "services": {
            "payment_card_uah_hpp": {
                "code": "payment_card_uah_hpp",
                "method": "payment_card",
                "flow": "hpp",
                "currency": "UAH",
                "fields": [],
                "amount_min": 0.01,
                "amount_max": 1000000
            },
            "test_UAH_test": {
                "code": "test_uah_test",
                "method": "test",
                "flow": "test",
                "currency": "UAH",
                "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_uah_hpp",
            "service_method":"payment_card",
            "service_currency":"UAH",
            "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_uah_hpp"
              }
            }
        },
        "links":{
            "self":"/api/payment-services/comcps_u1xxlHVw1NyeqmjJ"
        }
      },
      {
        "type":"payment-services",
        "id":"comcps_TEKVfH0di0vGimkF",
        "attributes":{
            "service":"applepay_uah_hpp",
            "service_method":"applepay",
            "service_currency":"UAH",
            "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":"UAH",
            "test_mode": true
        },
        "relationships":{
            "payment-method":{
              "data":{
                  "type":"payment-methods",
                  "id":"applepay"
              }
            },
            "payment-service":{
              "data":{
                  "type":"payment-services",
                  "id":"applepay_uah_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_uah_hpp",
            "service_method": "payment_card",
            "service_currency": "UAH",
            "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_uah_hpp"
                }
            }
        },
        "links": {
            "self": "/api/payment-services/comcps_u1xxlHVw1NyeqmjJ"
        }
    }
}

Ініціювання інвойсу¶

Через публічний API¶

Attention

Публічне API підтримує ініціювання інвойсів, якщо в налаштуваннях облікового запису для платежів вимкнено параметр «Тільки приватний API» (Forbid public access: FALSE).

Налаштування → Опції платежів

Payment Options

API: PUBLIC

Авторизація: Public keys

Endpoint: /payment-invoices

Method: POST

Обов'язкові поля запиту:

public_key - публічний ключ акаунту
reference_id - унікальний ідентифікатор операції на боці мерчанта
service - ідентифікатор сервісу, наприклад payment_card_uah_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_uah_hpp",
"currency": "UAH",
"amount": 123.45
}

Відповідь

{
    "data": {
        "id": "cpi_QGcJxoBxnYStkuvN",
        "serial_number": "QGcJxoBxnYStkuvN",
        "created": 1595846278,
        "test_mode": true,
        "reference_id": "7135b08b-701b-4fbc-a7d2-b2763d96d415",
        "currency": "UAH",
        "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_uah_hpp",
        "service_method": "payment_card",
        "service_flow": "hpp",
        "service_currency": "UAH",
        "metadata": {
            "merchant_url": "https://lets.doc.it"
        },
        "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"
        }
    }
}

Через HTML-форму¶

Посилання для оплати (а також QR-код) - простий і зручний метод для прийому платежів, детальну інформацію про який ви можете прочитати у відповідному розділі.

API: PUBLIC

Авторизація: Public keys

Endpoint: /payment-invoices/process

Method: POST

Обов'язкові параметри:

public_key — публічний ключ
service — *ідентифікатор сервісу, наприклад payment_card_uah_hpp: ви можете побачити повний список доступних сервісів у панелі керування або у відповіді на запит по приватному API*
currency — валюта інвойсу
amount — сума інвойсу, приклад: 100.55

обов`язковий параметр, якщо в запиті відправляється об`єкт customer з даними платника:

customer[reference_id] — унікальний ідентифікатор клієнта в системі

Відправка даних HTML-форми

<form action="https://cardgate-staging.psp.name/public-api/payment-invoices/process" method="post">
    <input type="hidden" name="public_key" value="<your_public_key>" />
    <input type="hidden" name="currency" value="UAH" />
    <input type="hidden" name="amount" value="100" />
    <input type="hidden" name="service" value="paypal_UAH_hpp" />
    <input type="hidden" name="customer[reference_id]" value="test12345"/>
    <input type="hidden" name="customer[name]" value="Test Customer"/>
    <input type="hidden" name="customer[address][full_address]" value="Test Address"/>
    <input type="submit" value="Pay" />
</form>

Ви можете ознайомитися з повним переліком параметрів для Checkout у відповідному розділі.

Через приватний API¶

API: PRIVATE

Авторизація: BasicAuth

Endpoint: /payment-invoices

Method: POST

Обов'язкові поля:

reference_id - унікальний ідентифікатор операції на боці мерчанта
service - ідентифікатор сервісу, наприклад payment_card_uah_hpp. Список усіх доступних сервісів можна подивитися в особистому кабінеті або отримати відповідь на запит
currency - валюта платежу
amount - сума у float форматі, наприклад 100.55

Додаткові поля:

flow - визначає тип інвойсу. Може приймати значення: charge, verify. У разі відсутності параметра у запиті за замовчуванням приймається значення charge
service_fields - обов'язковий параметр у деяких сервісах, які вимагають передачі реквізитів.
test_mode - ознака тестової / "бойової" операції. Може приймати значення true, false. У разі відсутності параметра у запиті за замовчуванням приймається значення false

description

customer

reference_id обов'язковий атрибут за наявності об'єкта у запиті

name

email

phone

metadata

metadata

return_url - універсальний URL для повернення користувача після оплати

return_urls - спеціальний об'єкт із 3-ма варіантами URL для повернення користувача на підставі статусу платежу

success

fail

pending обов'язковий атрибут за наявності об'єкта у запиті

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":"UAH", "service":"payment_card_uah_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": "UAH", "service_currency": "UAH", "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_uah_hpp" } }, "payment-method": { "data": { "type": "payment-methods", "id": "payment_card" } }, "customer": { "data": { "type": "customers", "id": "cus_Tjhe1ufEB3kRrgWy" } } }, "links": { "self": "/api/payment-invoices/cpi_HeSWMM9LvQonCcQc" } } }

Реконсиляція платежу (за 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": "UAH", "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_uah_hpp", "service_method": "payment_card", "service_flow": "hpp", "service_currency": "UAH", "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": "UAH", "service_currency": "UAH", "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_uah_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": "UAH", "service_currency": "UAH", "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_uah_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": "UAH", "service_currency": "UAH", "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_uah_hpp" } }, "payment-method": { "data": { "type": "payment-methods", "id": "payment_card" } }, "customer": { "data": { "type": "customers", "id": "cus_Tjhe1ufEB3kRrgWy" } } }, "links": { "self": "/api/payment-invoices/cpi_Qtg8wyWcnSYLksFh" } } ] }

Повернення платежу (за ID)¶

Через приватний API¶

API: PRIVATE

Авторизація: BasicAuth

Endpoint:

/payment-invoices/{id}/refund — для здійснення операції повернення по ідентифікатору інвойсу

Method: POST

Приклади

Запит

{ "data": { "type": "refund", "id": "cpi_XYZ4eaixXywfgXxX", "attributes": { "amount": "1" } } }

Відповідь

{ "data": { "type": "payment-invoices", "id": "cpi_XYZ4eaixXywfgXxX", "attributes": { "serial_number": "RMvSZiTZbC09i2bl", "status": "refunded", "resolution": "ok", "moderation_required": false, "amount": 1, "payment_amount": 1, "currency": "UAH", "service_currency": "UAH", "reference_id": "payment-test", "test_mode": false, "fee": 0, "deposit": 1, "processed": 1672925516, "processed_amount": 1, "refunded_amount": 1, "processed_fee": 0, "processed_deposit": 1, "metadata": [], "flow_data": { "action": "https://cardgate-staging.psp.name/hpp/cgi_Sa0JoAaSixZoYwNs", "method": "GET", "params": [], "metadata": { "sid": "cgi_XxXJoAaSixZoAbCs", "token": "eyJ0eXAiOiJKV1QiLCJhbGciOi00UzI1NiJ9.eyJzaWQiOiJjZ2lfU200Sm9BYVNpeFpvWXdOcyIsImV4cGlyZXMiOm51bGwsImV4cCI6MTY3MzA5ODIwOX0.S6cY7CEGP3nFi0LIu84LeUHRbhn427yWXnEcv00wbSQ" } }, "flow": "hpp", "payment_flow": "charge", "created": 1672925409, "updated": 1672925516, "payload": { "token": null, "auth_type": "public_token", "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": "payment", "descriptor": null, "callback_url": "https://example.com", "return_url": "https://example.com", "return_urls": { "fail": null, "pending": null, "success": null }, "original_data": { "original_id": "304585123", "provider_code": "null", "original_refund_id": null, "merchant_account_id": "null", "original_resolution": null, "original_resolution_message": "Transaction successful", "original_merchant_account_id": "2415" }, "rrn": "123456835789", "arn": null, "approval_code": "123456", "reserved_amount": null, "reserve_expires": null, "unreserved": null, "source": "merchant_api", "callback_logs": [], "charged_back_amount": null, "resolution_message": null, "hpp_url": "https://api.example.com/redirect/hpp/?cpi=cpi_XYZ4eaixXywfgXxX" }, "relationships": { "payment-service": { "data": { "type": "payment-services", "id": "payment_card_uah_hpp" } }, "payment-method": { "data": { "type": "payment-methods", "id": "payment_card" } }, "customer": { "data": { "type": "customers", "id": "cus_xDcCCKFFoEElGG5u" } }, "active-payment": { "data": { "type": "payments", "id": "null" } } }, "links": { "self": "/api/payment-invoices/cpi_XYZ4eaixXywfgXxX" } } }

Коди стану HTTP, що використовуються у відповідях¶

Приклади відповідей з кодами та описами помилок

401 (unauthorized)

{ "errors": [ { "status": "Unauthorized", "code": "401" } ] }

404 (not found)

{ "errors": [ { "status": "Not Found", "code": "404" } ] }

405 (incorrect method)

{ "errors": [ { "status": "Method Not Allowed", "code": "405" } ] }

422 (validation error)

{ "errors": { "amount": "This value should be greater than 0." } }

500 (internal server error)

{ "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 або викликати метод запиту статусу для уточнення стану операції.

Код	Опис
`200 OK`	Запит відправлений успішно
`201 Created`	POST запит на створення інвойсу виконано успішно

Код	Тип	Опис	Інструкції
`400 Bad Request`	Транспортна	Запит невалідної структури, сервер не може його обробити	Необхідно запросити статус операції (якщо використано правильний метод, але на запит статусу отримано помилку 404, можна вважати запит неуспішним і повторити операцію)
`401 Unauthorized`	Авторизації	Для отримання запитаної відповіді потрібна автентифікація	Перевірити дані авторизації. Запит фінально невдалий. Операція не створилася на боці платформи (якщо помилка виникла під час створення, не за інших методів)
`403 Forbidden`	Авторизації	У клієнта немає прав доступу на виклик методу	Перевірити дані авторизації. Запит фінально невдалий. Операція не створилася на боці платформи (якщо помилка виникла під час створення, не за інших методів)
`404 Not Found`	Валідації	Сервер не може знайти запитуваний метод чи ресурс	У запиті вказано некоректний метод чи операції не існує (за коректного запиту статусу)
`405 Method Not Allowed`	Валідації	Метод відправки запиту не може бути використаний	Запит фінально не успішний. Операція не створилася на боці платформи (якщо помилка виникла під час створення, не за інших методів)
`409 Conflict`	Валідації	Сутність із таким ідентифікатором вже існує. У відповіді повернеться код і повідомлення помилки, в тілі повернуться дані існуючої операції	Обробити тіло відповіді з раніше створеною операцією згідно з бізнес-логікою на боці мерчанта
`422 Unprocessable Entity`	Валідації	Сервер не може прийняти запит (некоректні дані або налаштування облікового запису)	Запит фінально неуспішний. Операція не створилася на боці платформи (якщо помилка виникла під час створення, не за інших методів)

Код	Опис	Інструкції
`500 Internal Server Error`	Внутрішня помилка серверу. Не гарантує помилки створення операції.	Необхідно запросити статус операції. У разі відсутності операції на сервері можна повторно викликати метод створення
`502 Bad Gateway`	Проблема обробки запиту. Визначено недійсний шлюз. Не гарантує помилки створення операції.	Необхідно запросити статус операції. У разі відсутності операції на сервері можна повторно викликати метод створення
`503 Service Unavailable`	Сервер зараз недоступний. Не гарантує помилку створення операції. Необхідно запросити статус операції. У разі відсутності операції на сервері можна повторно викликати метод створення
`504 Gateway Timeout`	Сервер не зміг повернути відповідь за певний проміжок часу. Не гарантує помилку створення операції.	Необхідно запросити статус операції. У разі відсутності операції на сервері можна повторно викликати метод створення