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

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

Клієнт формує замовлення на сайті Мерчанта.
Щоб надати клієнту можливість вибору варіанта оплати, мерчант відправляє передзапит платежу і отримує у відповіді від платформи 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":"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).

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

Payment Options

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 - *обов'язковий параметр у деяких сервісах, які вимагають передачі реквізитів

Наприклад, bank_transfer_usd_hpp

  "service_fields": {
    "account_number": "UA213223130000026007233566001"
  }

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

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

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