Cascad – Документация

Возможности
Решения
Как работает
- Как это работает
- Demo Shop
- API документация
- Консультация
Инфо
- О нас
- Контакты

Рус

Консультация

Рус

Вход

Документация

Аутентификация
Аккаунт
Платежи
Callbacks

Содержание:

Доступы к API

Публичный API

Приватный API

Аутентификация.

Доступы к API

Cascad API построены с учётом REST и используют JSON-формат и стандартные коды ответов HTTP для обмена данными.

Публичный API

Адрес для запросов: pay.cascad.com/public-api/

В запросах для публичного API используется Публичный ключ, боевой (live) или тестовый (test).

Ключи для интеграции находятся в настройках аккаунта в разделе «Интеграция».

Приватный API

Адрес для запросов: pay.cascad.com

Для авторизации используются ID аккаунта как Login (Username) и ключ API как Password. Данные параметры находятся в настройках коммерческого аккаунта в разделе «Интеграция».

Стандарт BasicAuth: Authorization = Basic base64(username:password)


  curl -X POST \
  pay.cascad.com/payment-invoices \
  -H 'Accept: */*' \
  -H 'Authorization: Basic Y29tYV92VDZMRFUwVHhPeG1iT290OkJlTlZRQ2hLcFV2RUxac3gwVmVpbnRaUmNlSmFWSWdrZVY2N1NvOVB0Wnc=' \
  -d '{...}'

Содержание:

Получение данных аккаунта

Балансы

Аккаунт.

Получение данных аккаунта

Endpoint: /account

Метод: GET

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


{
  "data": {
    "type": "account",
    "id": "coma_CebLG6xR7jOhQmkD",
    "attributes": {
       "status": "active",
       "name": "MyAccount",
       "icon": "https://example.com/images/coma_CebLG6xR7jOhQmkD/logo.png?1583399986",
       "description": "",
       "website": "https://example.com",
       "payment_fee_shift_out": false,
       "hp_domain": "https://example.eu/",
       "payment_options": {
           "descriptor_template": null,
           "attempts_limit": 5,
           "disabled_services": [
               "comcps_HSORYCGLJ237V07d",
               "comcps_a8WLGWFgNDm1jA48"
           ],
           "disable_new_services": true,
           "reverse_fee": false,
           "fee_strategy": "internal",
           "invoice_lifetime": 2880,
           "forbid_public_creation": false,
           "public_zero_fee": false,
           "public_fee": false,
           "expose_internal_data": true,
           "bypass_hpp": true,
           "force_commerce_return_url": true,
           "send_operation_context_on_return": true,
           "refund_fee": false,
           "recurrent": false,
           "allow_overwrite_descriptor": false
       },
       "payout_options": {
           "descriptor_template": null,
           "disabled_services": [],
           "batch_options": {
               "attempts_limit": 5,
               "processing_mode": "parallel"
           },
           "methods": [],
           "disable_new_services": false,
           "reverse_fee": true,
           "fee_strategy": "internal",
           "moderation_required": false,
           "invoice_lifetime": 30,
           "split_mode": false,
           "attempts_limit": 5,
           "parallel_mode": false,
           "allow_partially": false,
           "public_zero_fee": false,
           "public_fee": false,
           "expose_internal_data": false
       },
       "api_key": "jA55tDxgWwROc******5L0XtZZW2hKbsNLxBXs",
       "api_key_updated": 1581174500,
       "live_public_key": "pk_live_gHJXSMdFxG********ncFZDOhMBaf0MYkk",
       "live_private_key": "sk_live_r52mIq_qbL497********g-Vr8pfoN6Ojrw98E",
       "test_public_key": "pk_test_eCEOeg*****7M46Rv3bIn2Ag",
       "test_private_key": "sk_test_0Jb_N2x*************LbHXW0VC6wRcGf_Qxs1DAs",
       "callback_url": "https://example.site/026c96db-be91-481e-b7c6-4a82bac744a7",
       "ledger_scheme": "simple",
       "api_ip_white_list": [],
       "created": 1556285176,
       "updated": 1583327142,
       "currency_accounts": {
           "EUR": {
               "active_balance": "11.00",
               "pending_balance": "1.00",
               "reserved_balance": "0.00",
               "overdraft_limit": "10.00"
           },
           "BTC": {
               "active_balance": "0.00000000",
               "pending_balance": "0.00000000",
               "reserved_balance": "0.00000000",
               "overdraft_limit": "0.00000000"
           },
           "USD": {
               "active_balance": "0.22",
               "pending_balance": "2.00",
               "reserved_balance": "0.00",
               "overdraft_limit": "10.00"
           }
       },
       "report": true,
       "time_zone": "Europe/Kiev"
    },
    "links": {
      "self": "/api/account"
    }
  }
}

Балансы

Запрос на получение данных аккаунта содержит объект с балансами по валютам — currency_accounts :

Active (active_balance) — активный баланс (доступные средства для вывода)
Pending (pending_balance) — баланс с суммами в обработке (включает в себя незавершенные выплаты)
Reserved (reserved_balance) — «замороженный» баланс (может быть установлено резервирование части суммы принятых платежей на определённый период)
Overdraft (overdraft_limit) — Овердрафт лимит (доступные кредитные средства)


{
  "currency_accounts": {
  "EUR": {
     "active_balance": "11.00",
     "pending_balance": "1.00",
     "reserved_balance": "0.00",
     "overdraft_limit": "10.00"
    },
    "BTC": {
      "active_balance": "0.00000000",
      "pending_balance": "0.00000000",
      "reserved_balance": "0.00000000",
      "overdraft_limit": "0.00000000"
    },
    "USD": {
      "active_balance": "0.22",
      "pending_balance": "2.00",
      "reserved_balance": "0.00",
      "overdraft_limit": "10.00"
    }
  }
}

Содержание:

Предзапрос платежа через публичный API

Получение списка доступных сервисов через приватный API

Полный список сервисов

Данные сервиса по ID

Инициирование инвойса

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

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

Статусы инвойсов

Перечень статусов

Идентификация платежа

Реконсиляция платежа (по ID)

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

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

Получить полный список инвойсов (через приватный API)

Используемые в ответах коды состояния HTTP

2xx Успешные

4xx Ошибки на стороне клиента

5xx Ошибки на стороне сервера

Host-to-host интеграция для получения платежей

Начало

Общая схема взаимодействия

Создание платежного инвойса

Отправка данных карты на Card Gate

(для 3DS) Перенаправление пользователя на ACS

Приём платежей с перенаправлением пользователя на платежную страницу.

Предзапрос платежа через публичный API

Предзапросы используются для получения списка доступных для данной валюты сервисов.

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

Endpoint: /payment-prerequest

Method: POST


Запрос
Ответ


{
  "public_key" : "pk_test_ClSQHi2T9WXuFa76WcwwBB6rspRpg6ANM69cS9zNOJy",
  "currency" : "UAH"
}{
  "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

Полный список сервисов

Endpoint: /payment-services

Method: GET


JSON


{
"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": "GBP",
        "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"
    }
  }
]
}{
"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": "GBP",
        "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

Endpoint: /payment-services/{id}

Method: GET

Значение ID: из предыдущего запроса


JSON


{
    "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"
        }
    }
}{
    "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

Внимание

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

Endpoint: /payment-invoices

Method: POST

Обязательные поля запроса:

public_key — публичный ключ аккаунта
reference_id — уникальный идентификатор операции на стороне мерчанта
service — идентификатор сервиса, например payment_card_usd_hpp. Список всех доступных сервисов можно посмотреть в настройках платежей
currency — валюта платежа
amount — сумма в float формате, например 100.55

Дополнительное поле:

description


Запрос
Ответ


{
  "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
}{
  "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"
    }
}
}

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

Endpoint: /payment-invoices

Method: POST

Обязательные поля:

reference_id — уникальный идентификатор операции на стороне мерчанта
service— идентификатор сервиса, например payment_card_usd_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 для отправки уведомлений при изменении статуса операции
gateway_options — опции модификации шлюза, к примеру — для видоизменения платёжной страницы (необходимо уточнять набор и возможные значения для каждого конкретного аккаунта)


Запрос
Ответ


{
  "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": "[email protected]",
            "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"
      }
  }
}{
  "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": "[email protected]",
            "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"
      }
  }
}{
"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",
        "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": [],
        "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"
    }
}
}

Статусы инвойсов

Перечень статусов

Статус платежа — определяет этап проведения транзакции. Статус может быть промежуточным и финальным.

Статус	Финальный	Значение
created		Начальный статус после создания инвойса, процессирование не начато. В ответе должен быть возвращен 201 (Created) статус-код HTTP, что означает успешное создание инвойса
expired		Время ожидания обработки платежного инвойса превысило лимит (заданный в настройках выплаты свойством invoice_lifetime)
process_pending		Результат обработки транзакции неизвестен (например, не получен ответ платежного провайдера) и также может быть неизвестен в течение продолжительного времени
processed		Подтверждает успешное процессирование платежа
process_failed		Означает сбой процессирования. Статус может быть присвоен в случае повторяющейся ошибки и сбое получения ответа
refund_pending		Результат возврата неизвестен (например, не получен ответ платежного провайдера) и также может быть неизвестен в течение продолжительного времени
partially_refunded		Возврат произведен на сумму, меньшую чем сумма, указанная в инвойсе
refunded		Платеж полностью возвращен
refund_failed		Возврат завершился неуспешно

* — Статус считается финальным, однако после него платеж может быть отклонен по дополнительным причинам или отправлен на возврат (рефанд или чарджбэк)

** — Статус определяется как финальный после достижения максимального количества попыток провести транзакцию (по умолчанию — 5)

Идентификация платежа

На разных этапах приема платежа идентификаторы обрабатываются с разными наименованиями. Связи между ними отображены на схеме ниже.

Receiver Reference Number (RRN, номер получателя транзакции) и Acquirer Reference Number (ARN, номер транзакции, присваиваемый эквайером) используются только для карточных расчетов.

Реконсиляция платежа (по ID)

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

Endpoint: /payment-invoices/{id}

Метод: 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"
    }
}
}{
"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

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_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"
    }
}
}{
"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"
    }
}
}

Получить полный список инвойсов (через приватный API)

Endpoint: /payment-invoices

Method: GET


Пример


{
"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": [],
            "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"
        }
    }
]
}{
"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": [],
            "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"
        }
    }
]
}

Используемые в ответах коды состояния HTTP


401 (unauthorized)
 404 (not found)
405 (incorrect method)
422 (validation error)
500 (internal server error)


{
"errors": [
    {
        "status": "Unauthorized",
        "code": "401"
    }
]
}{
"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 ОK	Запрос выполнен успешно
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	Сервер не смог вернуть ответ за определённый промежуток времени. Не гарантирует ошибку создания операции.	Необходимо запросить статус операции. В случае отсутствия операции на сервере можно повторно вызвать метод создания

Внимание

Если создание операции прошло успешно, а на любой другой запрос получен ответ с 4XX или 5XX HTTP кодом — необходимо уточнять статус методом реконсиляции или через каналы коммуникации технической поддержки.

При использовании Callback метода оповещения — при получении ошибок необходимо дождаться Callback или вызвать метод запроса статуса для уточнения состояния операции.

Host-to-host интеграция для получения платежей

Начало

Крупные организации, выполняющие требования PCI DSS, могут использовать Host-to-host (H2H) интеграцию для получения карточных платежей.

Отправьте заявку службе поддержки, чтобы уточнить требования и включить для Вашего аккаунта режим H2H-платежей.

Общая схема взаимодействия

Создание платежного инвойса

Endpoint: /payment-invoices

Метод: POST


Пример запроса для инвойса
Пример ответа


{
"data": {
"type": "payment-invoices",
"attributes": {
"reference_id": "{guid}",
"description": "Payment by order#1",
"currency": "UAH",
"amount": 17,
"service": "payment_card_uah_hpp",
"return_url": "https://example.com/",
"callback_url": "https://example.com/payments/callback"
}
}
}{
"data": {
"type": "payment-invoices",
"attributes": {
"reference_id": "{guid}",
"description": "Payment by order#1",
"currency": "UAH",
"amount": 17,
"service": "payment_card_uah_hpp",
"return_url": "https://example.com/",
"callback_url": "https://example.com/payments/callback"
}
}
}{
"data": {
  "type": "payment-invoices",
  "id": "cpi_eqUNbE6SpIEmRB2K",
  "attributes": {
     "status": "process_pending",
     "resolution": "ok",
     "moderation_required": false,
     "amount": 17,
     "payment_amount": 17,
     "currency": "UAH",
     "service_currency": "UAH",
     "reference_id": "{guid}",
     "test_mode": true,
     "fee": 0,
     "deposit": 17,
     "processed": null,
     "processed_amount": null,
     "processed_fee": null,
     "processed_deposit": null,
     "metadata": [

     ],
     "flow_data": {
        "action": "https:\/\/our.pay_domain\/hpp\/7b3df799-5608-56fa-a26b-5a9b3c26bb5c",
        "method": "GET",
        "params": [

        ],
        "metadata": {
           "sid": "7b3df799-5608-56fa-a26b-5a9b3c26bb5c",
           "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzUxMiJ9...fGbuc"
        }
     },
     "flow": "hpp",
     "created": 1567434682,
     "updated": 1567434682,
     "payload": [

     ],
     "description": "Payment by order#1",
     "callback_url": "pay.cascad.com\/payments\/callback",
     "return_url": "pay.cascad.com"
  },
  "relationships": {
     "payment-service": {
        "data": {
           "type": "payment-services",
           "id": "payment_card_uah_hpp"
        }
     },
     "payment-method": {
        "data": {
           "type": "payment-methods",
           "id": "payment_card"
        }
     },
     "customer": {
        "data": null
     }
  },
  "links": {
     "self": "\/api\/payment-invoices\/cpi_eqUNbE6SpIEmRB2K"
  }
}
}

Отправка данных карты на Card Gate

API URL: при интеграции выдаётся менеджером

Endpoint: /payment-invoices

Метод: POST

Авторизация: bearerToken (передается параметр token, полученный в ответ на запрос создания инвойса, объект flow_data → metadata)


Пример запроса с карточными данными
Пример ответа


{
"data": {
"type": "sale-operation",
"attributes": {
  "card_number": "5519283812030000",
  "card_holder": "Card Holder",
  "cvv": "123",
  "exp_month": "10",
  "exp_year": "35"
}
}
}{
"data": {
"type": "sale-operation",
"attributes": {
  "card_number": "5519283812030000",
  "card_holder": "Card Holder",
  "cvv": "123",
  "exp_month": "10",
  "exp_year": "35"
}
}
}{
"status": "auth_required",
"auth_mode": "3ds",
"auth_payload": {
  "action": "https:\/\/acs.pay_domain\/acspage\/cap?RID=8\u0026VAA=A",
  "method": "POST",
  "params": {
     "MD": "999999999",
     "PaReq": "eJxVUlFvVA2jYv2jAQfuZfoD5v2E5KfQlLFJ2jAQfuZfoD5v2E5KQqurpe5os5wRBJU6dZCX79bszlDIrUe6+zWRkwjEe0qVHL3dmbqjeATGvs6XKz2Np1GBFSxq3r684PeiZvQbwnXOj9i951XdPeC4HWHT5bV1v+3z29+Vgs\/OIi+9oe48acmxbs8VxVT7cFNkaX3+raapimUYqiZPbGz2CAOvRCP6gbytXany0njnTX07Y3Ii6VYY9u64EQNFz3J5OPlalzjc\/4nyTv63+Lo+rfR6tFtlbfnofQDCDmaXpUEdS3SmcbXhU7MLJSwQ12gwovceazvouxlVLxmX8EgKkXeDuMSs7UoPPH47\/yLbkeV+MU3SeTqst8PT5mfi9m5WZtmv+eMzCzuTzr0rcpzulYTmVbAfBLejA8KAsIlhlij6b8b+AbaDvJg=",
     "TermUrl":"https:\/\/pay.cascad.com\/3ds-return?pid=pay_Hjh3kMlNdqE4WpOmNPCoIgFU_K1_nM"
  }
}
}

(для 3DS) Перенаправление пользователя на ACS

В ответе на запрос /payment/sale объект auth_payload cодержит данные для 3D-Secure.

На action URL нужно передать параметры формы params методом method.


Пример


"auth_payload": {
  "action": "https:\/\/acs.pay_domain\/acspage\/cap?RID=8\u0026VAA=A",
  "method": "POST",
  "params": {
     "MD": "999999999",
     "PaReq": "eJxVUlFvVA2jYv2jAQfuZfoD5v2E5KfQlLFJ2jAQfuZfoD5v2E5KQqurpe5os5wRBJU6dZCX79bszlDIrUe6+zWRkwjEe0qVHL3dmbqjeATGvs6XKz2Np1GBFSxq3r684PeiZvQbwnXOj9i951XdPeC4HWHT5bV1v+3z29+Vgs\/OIi+9oe48acmxbs8VxVT7cFNkaX3+raapimUYqiZPbGz2CAOvRCP6gbytXany0njnTX07Y3Ii6VYY9u64EQNFz3J5OPlalzjc\/4nyTv63+Lo+rfR6tFtlbfnofQDCDmaXpUEdS3SmcbXhU7MLJSwQ12gwovceazvouxlVLxmX8EgKkXeDuMSs7UoPPH47\/yLbkeV+MU3SeTqst8PT5mfi9m5WZtmv+eMzCzuTzr0rcpzulYTmVbAfBLejA8KAsIlhlij6b8b+AbaDvJg=",
     "TermUrl": "https:\/\/pay.cascad.com\/3ds-return?pid=pay_Hjh3kMlNdqE4WpOmNPCoIgFU_K1_nM"
  }
}"auth_payload": {
  "action": "https:\/\/acs.pay_domain\/acspage\/cap?RID=8\u0026VAA=A",
  "method": "POST",
  "params": {
     "MD": "999999999",
     "PaReq": "eJxVUlFvVA2jYv2jAQfuZfoD5v2E5KfQlLFJ2jAQfuZfoD5v2E5KQqurpe5os5wRBJU6dZCX79bszlDIrUe6+zWRkwjEe0qVHL3dmbqjeATGvs6XKz2Np1GBFSxq3r684PeiZvQbwnXOj9i951XdPeC4HWHT5bV1v+3z29+Vgs\/OIi+9oe48acmxbs8VxVT7cFNkaX3+raapimUYqiZPbGz2CAOvRCP6gbytXany0njnTX07Y3Ii6VYY9u64EQNFz3J5OPlalzjc\/4nyTv63+Lo+rfR6tFtlbfnofQDCDmaXpUEdS3SmcbXhU7MLJSwQ12gwovceazvouxlVLxmX8EgKkXeDuMSs7UoPPH47\/yLbkeV+MU3SeTqst8PT5mfi9m5WZtmv+eMzCzuTzr0rcpzulYTmVbAfBLejA8KAsIlhlij6b8b+AbaDvJg=",
     "TermUrl": "https:\/\/pay.cascad.com\/3ds-return?pid=pay_Hjh3kMlNdqE4WpOmNPCoIgFU_K1_nM"
  }
}

Содержание:

Настройка

Запросы Callbacks

Проверка подлинности

Превышение времени ожидания (тайм-аут)

Автоповтор отправки

Дублирование

Пакетная обработка

Доставка не по порядку

IP-адреса

Callbacks.

Callbacks позволяют получать уведомления, когда изменяется статус операции.

Чтобы настроить Callbacks для операций, необходимо задать адрес в callback_url в настройках интеграции или отправлять этот параметр в запросе.

Callback — асинхронная функция и не рекомендуется для задач с жестким ограничением по времени. Существует немалая вероятность, что Ваше приложение получит Callbacks не в порядке отправки или они продублируются. Для задач с жестким временным ограничением мы рекомендуем использовать реконсиляцию по API для обновления данных в системе.

Настройка

Для настройки Callbacks Вам нужно перейти к настройкам аккаунта и добавить значение «Callback URL».

Запросы Callbacks

HTTP запрос, который мы отправим на Ваш callback_url, будет обладать следующими характеристиками:

это будет POST запрос;
тело запроса будет передано в JSON API формате, как в открытом API;
объекты type и id обязательно будут в теле запроса (а не в url-параметре).

Ниже пример Callbacks для инвойса платежа:


{
"data": {
 "type": "payment-invoices",
 "id": "cpi_TV465FXkbGch3GNe",
 "attributes": {
    "status": "processed",
    "resolution": "ok",
    "moderation_required": false,
    "amount": 3.33,
    "payment_amount": 3.33,
    "currency": "UAH",
    "service_currency": "UAH",
    "reference_id": "{guid}",
    "test_mode": false,
    "fee": 0,
    "deposit": 3.33,
    "processed": 1564153164,
    "processed_amount": 3.33,
    "processed_fee": 0,
    "processed_deposit": 3.33,
    "metadata": [

    ],
    "flow_data": {
       "action": "https:\/\/pay.cascad.com\/hpp\/{guid}",
       "method": "GET",
       "params": [

       ]
    },
    "flow": "hpp",
    "created": 1564153017,
    "updated": 1564153164,
    "payload": {
       "payment_card": {
          "last": "1111",
          "mask": "511111******1111",
          "brand": "mastercard",
          "first": "511111",
          "issuer_name": "PUBLIC JOINT-STOCK COMPANY COMMERCIAL BANK PRIVATBANK",
          "issuer_country": "UA"
       }
    },
    "description": null,
    "callback_url": null
 },
 "relationships": {
    "payment-service": {
       "data": {
          "type": "payment-services",
          "id": "payment_card_uah_hpp"
       }
    },
    "payment-method": {
       "data": {
          "type": "payment-methods",
          "id": "payment_card"
       }
    },
    "customer": {
       "data": null
    }
 },
 "links": {
    "self": "\/api\/payment-invoices\/cpi_p<...>"
 }
}
}

Тело запроса Callback содержит тело соответствующей операции инвойса. Статусы инвойсов описаны в руководствах: платежей, выплат

Проверка подлинности

Cascad подписывает данные, используя ключи в хедере запроса X-Signature.

Алгоритм генерации:

$signature = base64_encode(sha1($secret . $callbackData . $secret, true));

где $secret— боевой («Live key») или тестовый («Test key») секретный ключ, который находится в настройках аккаунта;

$callbackData— неформатированный JSON код.

Чтобы убедиться в достоверности источника, сгенерируйте подпись используя соответствующий ключ и сравните с данными в Callback.

Превышение времени ожидания (тайм-аут)

Cascad выделяет три типа тайм-аутов для Callbacks:

1. Тайм-аут соединения (Connection Timeout): граничное время для установления начального соединения с HTTP-сервером URL Callbacks.

2. Тайм-аут чтения (Read Timeout): граничное время сообщения о прочтении данных HTTP сервера после установки соединения.

3. Общий тайм-аут отправки Callbacks (Total Callback Timeout): в дополнение к двум предыдущим, Cascad также проверяет общее время выполнения Callbacks.

Значения тайм-аутов:

Тип	Для тестового соединения	Для боевого соединения
Connection Timeout	10,000 мс	20,000 мс
Read Timeout	10,000 мс	20,000 мс
Execution Timeout	10,000 мс	60,000 мс

Автоповтор отправки

После успешного выполнения запроса Callbacks должен вернуться HTTP-код 200. Любые другие данные в ответе игнорируются.

Если вернулся другой HTTP-код, значит, запрос не доставлен. По умолчанию, невыполненный запрос повторно отправляется с промежутком ожидания между попытками:

1-й повтор запроса будет отправлен спустя 1 минуту после начальной попытки;

2-й повтор — спустя 2 минуты после 1-го повтора;

3-й — спустя 3 минуты после 2-го;

4-й — спустя 4 минуты после 3-го;

5-й — спустя 5 минут после 4-го;

и 6-й — спустя 6 минут после 5го.

и т.д. до 100 попыток или до получения 200 HTTP-кода

Существует возможность настройки интервала отправки и количества попыток

Отправьте запрос нашей службе поддержки, чтобы мы вместе подобрали наилучший вариант.

Вы можете переотправить запрос c панели управления, если хотите синхронизировать данные немедленно. Для этого нужно перейти к информации о переводе, выбрать вкладку Callbacks и кликнуть кнопку Отправить заново.

Дублирование

Из-за повторной отправки Callbacks есть вероятность, что приложение получит одни и те же данные несколько раз. Вы можете убедиться в идемпотентности операции (свойстве объекта или операции при повторном применении операции к объекту давать тот же результат, что и при первом), обнаружив такие дубликаты в данных приложения.

Это не является проблемой, если приложение определяет идемпотентность. Для контроля используйте параметр id в данных запроса Callbacks, т.к. его значение является уникальным для операции и позволяет её идентифицировать.

Пакетная обработка

Мы связываем Callbacks для близких статусов. Так что, если платеж сразу же перешел из статуса created(создан) в статус invoked(в обработке) и в статус processed(обработан), вы получите только один Callback с последним по времени статусом (т.е. processed).

Преимущество такого подхода: возможность избежать перегрузки Ваших серверов HTTP запросами и избавить Ваше приложение от необходимости усложнять логику взаимодействия с последовательными изменениями статуса. Ваше приложение должен заботить только последний статус объекта.

Доставка не по порядку

Callbacks могут приходить не по порядку из-за неполадок сети или сбоев отправки. Вы все равно можете установить правильную последовательность событий, ориентируясь на атрибут updatedв Callbacks. updated— это временная отметка, которая обновляется с каждым изменением ресурса.

IP-адреса

Для повышения безопасности взаимодействия между платформой Cascad и Вашим сервером, необходимо использовать белый список IP-адресов.

Узнать детальнее о доменах и IP адресах

Эта страница предназначена для работы разработчиков. Мы не создали версию страницы для мобильных.

Пожалуйста, откройте страницу на устройстве с разрешением экрана не менее 1260 px 🙂

Консультация.

Форма обратной связи.

Имя

Номер телефона*

Email*

Текст сообщения

Нажимая «Отправить», я подтверждаю что ознакомился с Публичным договором, и принимаю условия.

Спасибо за вашу заявку.

Мы свяжемся с вами в ближайшее время
и ответим на ваши вопросы .

Понятно

Содержание:

Аутентификация.

Доступы к API

Публичный API

Приватный API

Пример

Содержание:

Аккаунт.

Получение данных аккаунта

Пример ответа

Балансы

Пример ответа

Содержание:

Приём платежей с перенаправлением пользователя на платежную страницу.

Предзапрос платежа через публичный API

Примеры (JSON)

Получение списка доступных сервисов через приватный API

Полный список сервисов

Пример ответа

Данные сервиса по ID

Пример ответа

Инициирование инвойса

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

Внимание

Настройки → Опции платежей

Примеры (JSON)

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

Примеры (JSON)

Статусы инвойсов

Перечень статусов

Идентификация платежа

Примечание

Реконсиляция платежа (по ID)

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

Пример ответа

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

Пример ответа

Получить полный список инвойсов (через приватный API)

Пример ответа

Используемые в ответах коды состояния HTTP

Примеры ответов с кодами и описаниями ошибок

2xx Успешные

4xx Ошибки на стороне клиента

5xx Ошибки на стороне сервера

Внимание

Примечание

Host-to-host интеграция для получения платежей

Начало

Общая схема взаимодействия

Создание платежного инвойса

JSON

Отправка данных карты на Card Gate

JSON

(для 3DS) Перенаправление пользователя на ACS

JSON

Содержание:

Callbacks.

Примечание

Настройка

Запросы Callbacks

JSON

Примечание

Проверка подлинности

Примечание

Превышение времени ожидания (тайм-аут)

Автоповтор отправки

Существует возможность настройки интервала отправки и количества попыток

Примечание

Дублирование

Пакетная обработка

Доставка не по порядку

IP-адреса