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