Перейти к содержанию

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

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

Redirect to payment page scheme

  1. Клієнт формує замовлення на сайті мерчанта.

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

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

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

    Надсилання попереднього запиту не потрібно, якщо мерчант визначає метод оплати за клієнта і створює інвойс платежу після формування замовлення.

  4. Мерчант створює інвойс платежу з допомогою публічного або приватного API. Отримавши інвойс, CASCAD:

    • Ініціює транзакцію на боці провайдера.
    • Передає мерчантові дані для платіжної форми.
    • Відправляє Callback мерчанту з повідомленням про успішне створення інвойсу.

  5. Мерчант перенаправляє клієнта на сторінку платіжного провайдера з даними форми.

  6. На сторінці провайдера клієнт вводить реквізити для оплати. Провайдер надсилає запит на списання коштів емітенту.

  7. У випадку, якщо потрібен додатковий етап підтвердження платежу (верифікація 3DSecure або іншим способом), провайдер перенаправляє користувача на сторінку верифікації. Клієнт підтверджує платіж на сторінці верифікації і дані передаються емітенту.

  8. Емітент повертає результати оплати та завершує транзакцію.

  9. Провайдер фіксує статус транзакції та повертає його платформі CASCAD, а CASCAD у свою чергу перенаправляє дані мерчантові.

  10. Мерчант відображає клієнтові статус платежу на сторінках свого сайту.

  11. CASCAD відправляє мерчанту Callback з повідомленням про статус платежу.

  12. Для уточнення статусу транзакції мерчанта може провести реконсиляцію платежу за 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
    • individual_tax_id індивідуальний податковий номер (ІПН)
    • passport_series серія паспорта
    • passport_number номер паспорта
    • email
    • phone
    • metadata
  • metadata
    • purpose - "F108 33 Оплата гравцями участі в азартних іграх казино в мережі Інтернет"
      або
      "F108 35 Оплата гравцями участі в азартних іграх з букмекерської діяльності в мережі Інтернет"
      або
      "F108 (код діяльності) Призначення"
    Примітка для учасників МСС 7995

    Мерчант з 1 ліцензією: у разі відсутності поля "purpose" в "metadata", не передані параметри призначення та роду діяльності, автоматично буде фіксуватися код та призначення: "F108 (код діяльності) Оплата гравцям азартних ігор (деталізація роду діяльності) в мережі Інтернет"
    Мерчант з 2 та більше ліцензіями: у разі відсутності поля "purpose" в "metadata", не передані параметри призначення та роду діяльності, автоматично буде фіксуватися код та призначення: "F108 (код діяльності) Оплата гравцям азартних ігор (деталізація роду діяльності) в мережі Інтернет"" відповідно до першої ОТРИМАНОЇ ліцензії при співпраці

  • 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, що використовуються у відповідях

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

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