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

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

Клиент формирует заказ на сайте мерчанта.
Чтобы предоставить клиенту возможность выбора варианта для оплаты, мерчант отправляет предзапрос платежа и получает в ответе от платформы Spoynt список доступных методов.
Мерчант отображает список методов, и клиент выбирает удобный ему способ оплатить заказ.

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

Отправка предзапроса не требуется, если мерчант определяет метод оплаты за клиента и создает инвойс платежа после формирования заказа.
Мерчант создает инвойс платежа с помощью публичного или приватного API. Получив инвойс, Spoynt:
- Инициирует транзакцию на стороне провайдера.
- Передает мерчанту данные для платежной формы.
- Отправляет Callback мерчанту с уведомлением об успешном создании инвойса.
Мерчант перенаправляет клиента на страницу платёжного провайдера с данными формы.
На странице провайдера клиент вводит реквизиты для оплаты. Провайдер отправляет запрос на списание средств эмитенту.
В случае, если требуется дополнительный этап подтверждения платежа (верификация 3DSecure или другим способом), провайдер перенаправляет пользователя на страницу верификации. Клиент подтверждает платёж на странице верификации, и данные передаются эмитенту.
Эмитент возвращает результаты оплаты и завершает транзакцию.
Провайдер фиксирует статус транзакции и возвращает его платформе Spoynt, а Spoynt в свою очередь перенаправляет данные мерчанту.
Мерчант отображает клиенту статус платежа на страницах своего сайта.
Spoynt отправляет мерчанту Callback с уведомлением о статусе платежа.
Для уточнения статуса транзакции мерчанта может провести реконсиляцию платежа по ID либо получить полный список данных инвойсов с помощью приватного API. Также на портале доступно ежедневное получение отчетов по транзакциям.

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

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

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

API: PUBLIC

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

Endpoint: /payment-prerequest

Method: POST

Примеры

Запрос

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

Ответ

{
    "data": {
        "currency": "USD",
        "test_mode": true,
        "services": {
            "payment_card_usd_hpp": {
                "code": "payment_card_usd_hpp",
                "method": "payment_card",
                "flow": "hpp",
                "currency": "USD",
                "fields": [],
                "amount_min": 0.01,
                "amount_max": 1000000
            },
            "test_usd_test": {
                "code": "test_usd_test",
                "method": "test",
                "flow": "test",
                "currency": "USD",
                "fields": [
                    {
                        "key": "status",
                        "type": "string",
                        "label": {
                            "ru": "Статус",
                            "en": "Status",
                            "uk": "Статус"
                        },
                        "example": null,
                        "hint": {
                            "ru": "Введите статус",
                            "en": "Enter Status",
                            "uk": "Введіть статус"
                        },
                        "regexp": "^[a-zA-Z_]*$",
                        "required": true,
                        "position": 0
                    }
                ],
                "amount_min": 0.01,
                "amount_max": 9999999
            }
        },
        "methods": {
            "payment_card": {
                "code": "payment_card",
                "category": "payment_card",
                "description": "",
                "name": {
                    "en": "Payment card",
                    "ru": "Платежная карта",
                    "uk": "Платіжна карта"
                },
                "logo": "https://static.openfintech.io/payment_methods/payment_card/logo.svg",
                "icon": "https://static.openfintech.io/payment_methods/payment_card/icon.svg",
                "metadata": null,
                "position": null,
                "hide": null
            },
            "test": {
                "code": "test",
                "category": "alternative",
                "description": "",
                "name": {
                    "en": "Test",
                    "ru": "Тест",
                    "uk": "Тест"
                },
                "logo": "https://static.openfintech.io/payment_methods/test/logo.png",
                "icon": "https://static.openfintech.io/payment_methods/test/icon.svg",
                "metadata": null,
                "position": null,
                "hide": null
            }
        },
        "account": {
            "name": "4Docs",
            "description": "4Docs only",
            "icon": "https://static-dev.psp.name/images/default.svg?1595844446",
            "website": null
        }
    }
}

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

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

API: PRIVATE

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

Endpoint: /payment-services

Method: GET

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

{
  "meta":{
      "total":124,
      "pages":7,
      "page":1
  },
  "links":{
      "first":"/api/payment-services?page[number]=1&page[size]=20",
      "next":"/api/payment-services?page[number]=2&page[size]=20",
      "last":"/api/payment-services?page[number]=7&page[size]=20"
  },
  "data":[
      {
        "type":"payment-services",
        "id":"comcps_wQmYGz5RbkcgfdLI",
        "attributes":{
            "service":"test_xts_test",
            "service_method":"test",
            "service_currency":"XTS",
            "available":true,
            "active":false,
            "enabled":true,
            "amount_min":0.01,
            "amount_max":9999999,
            "fee_min":0,
            "fee_max":0,
            "fee_rate":0,
            "fee_fix":0,
            "reserve_lifetime":0,
            "reserve_rate":0,
            "currency":"GBP",
            "test_mode":true
        },
        "relationships":{
            "payment-method":{
              "data":{
                  "type":"payment-methods",
                  "id":"test"
              }
            },
            "payment-service":{
              "data":{
                  "type":"payment-services",
                  "id":"test_xts_test"
              }
            }
        },
        "links":{
            "self":"/api/payment-services/comcps_wQmYGz5RbkcgfdLI"
        }
      },
      {
        "type":"payment-services",
        "id":"comcps_u1xxlHVw1NyeqmjJ",
        "attributes":{
            "service":"payment_card_usd_hpp",
            "service_method":"payment_card",
            "service_currency":"USD",
            "available":true,
            "active":false,
            "enabled":true,
            "amount_min":0.01,
            "amount_max":1000000,
            "fee_min":0,
            "fee_max":0,
            "fee_rate":0,
            "fee_fix":0,
            "reserve_lifetime":0,
            "reserve_rate":0,
            "currency":"GBP",
            "test_mode": true
        },
        "relationships":{
            "payment-method":{
              "data":{
                  "type":"payment-methods",
                  "id":"payment_card"
              }
            },
            "payment-service":{
              "data":{
                  "type":"payment-services",
                  "id":"payment_card_usd_hpp"
              }
            }
        },
        "links":{
            "self":"/api/payment-services/comcps_u1xxlHVw1NyeqmjJ"
        }
      },
      {
        "type":"payment-services",
        "id":"comcps_TEKVfH0di0vGimkF",
        "attributes":{
            "service":"applepay_usd_hpp",
            "service_method":"applepay",
            "service_currency":"USD",
            "available":true,
            "active":false,
            "enabled":true,
            "amount_min":0.01,
            "amount_max":1000000,
            "fee_min":0,
            "fee_max":0,
            "fee_rate":0,
            "fee_fix":0,
            "reserve_lifetime":0,
            "reserve_rate":0,
            "currency":"GBP",
            "test_mode": true
        },
        "relationships":{
            "payment-method":{
              "data":{
                  "type":"payment-methods",
                  "id":"applepay"
              }
            },
            "payment-service":{
              "data":{
                  "type":"payment-services",
                  "id":"applepay_usd_hpp"
              }
            }
        },
        "links":{
            "self":"/api/payment-services/comcps_TEKVfH0di0vGimkF"
        }
      }
  ]
}

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

API: PRIVATE

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

Endpoint: /payment-services/{id}

Method: GET

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

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

{
    "data": {
        "type": "payment-services",
        "id": "comcps_u1xxlHVw1NyeqmjJ",
        "attributes": {
            "service": "payment_card_usd_hpp",
            "service_method": "payment_card",
            "service_currency": "USD",
            "available": true,
            "active": false,
            "enabled": true,
            "amount_min": 0.01,
            "amount_max": 1000000,
            "fee_min": 0,
            "fee_max": 0,
            "fee_rate": 0,
            "fee_fix": 0,
            "reserve_lifetime": 0,
            "reserve_rate": 0,
            "currency": "GBP",
            "test_mode": true
        },
        "relationships": {
            "payment-method": {
                "data": {
                    "type": "payment-methods",
                    "id": "payment_card"
                }
            },
            "payment-service": {
                "data": {
                    "type": "payment-services",
                    "id": "payment_card_usd_hpp"
                }
            }
        },
        "links": {
            "self": "/api/payment-services/comcps_u1xxlHVw1NyeqmjJ"
        }
    }
}

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

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

Attention

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

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

Payment Options

Прямой API запрос¶

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. В случае отсутствия параметра в запросе по умолчанию принимается значение charge
service_fields - *обязательный параметр в некоторых сервисах, которые требуют передачи реквизитов

Например для bank_transfer_usd_hpp

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

test_mode - признак тестовой / "боевой" операции. Может принимать значения true, false. В случае отсутствия параметра в запросе по умолчанию принимается значение false
description
customer - объект, который содержит базовые данные клиента и любые связанные с ним метаданные
- reference_id обязательный атрибут при наличии объекта в запросе
- name
- email
- phone
- individual_tax_id
- date_of_birth
- metadata
- address - объект для передачи адресных данных пользователя
  - country
  - region
  - city
  - street
  - full_address
  - post_code
metadata
return_url - универсальный URL для возврата пользователя после оплаты
return_urls - специальный объект с 3-мя вариантами URL для возврата пользователя на основании статуса платежа
- success
- fail
- pending обязательный атрибут при наличии объекта в запросе
callback_url - URL для отправки уведомлений Callbacks при изменении статуса операции
gateway_options - опции модификации шлюза, к примеру — для видоизменения платёжной страницы (необходимо уточнять набор и возможные значения для каждого конкретного аккаунта)
expires - дата и время истечения срока действия инвойса в формате DateTime; возможный для установления срок действия инвойса при этом - от 14 минут до 2 суток от даты создания

Примеры (JSON)

Запрос

{
    "data":{
        "type":"payment-invoices",
        "attributes":{
            "reference_id":"a30ebec4-035c-4fc5-8c48-b525ca601f37",
            "amount":100,
            "currency":"USD",
            "service":"payment_card_usd_hpp",
            "flow":"charge",
            "test_mode":true,
            "description":"Invoice Example",
            "gateway_options":{
                "cardgate":{
                "tokenize":false
                }
            },
            "customer":{
                "reference_id":"1203515",
                "email":"somename@domain.com",
                "name":"John Wick",
                "phone":"+380987654321",
                "metadata":{
                "key1":"value1",
                "key2":"value2"
                }
            },
            "metadata":{
                "key":"value"
            },
            "return_url":"https://example.com",
            "return_urls": {
                "success":"https://example.com/1",
                "pending":"https://example.com/2",
                "fail":"https://example.com/3"
            },
            "callback_url":"https://example.com",
            "expires": "2020-12-13T15:52:00+00:00"
            }
        }
    }

Ответ

    {
    "data": {
        "type": "payment-invoices",
        "id": "cpi_HeSWMM9LvQonCcQc",
        "attributes": {
            "serial_number": "HeSWMM9LvQonCcQc",
            "status": "process_pending",
            "resolution": "ok",
            "moderation_required": false,
            "amount": 100,
            "payment_amount": 100,
            "currency": "USD",
            "service_currency": "USD",
            "reference_id": "70d42236-2cc4-4e26-8f2f-987fd8fbc276",
            "test_mode": true,
            "fee": 0,
            "deposit": 100,
            "processed": null,
            "processed_amount": null,
            "refunded_amount": null,
            "processed_fee": null,
            "processed_deposit": null,
            "metadata": {
                "key": "value",
                "merchant_url": "https://lets.doc.it"
            },
            "flow_data": {
                "action": "https://cardgate-staging.psp.name/hpp/cgi_G0bsyhroZj802zQU",
                "method": "GET",
                "params": [],
                "metadata": {
                    "sid": "cgi_G0bsyhroZj802zQU",
                    "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzUxMiJ9.eyJzaWQiOiJjZ2lfRzBic3locm9aajgwMnpRVSIsImV4cCI6MTU5NzgzNDg5OH0.Vsjj8tcnKqFrxz5SynNdC0q8x_eQawJG9CJTAEUNm6JQG64En4zYij_DjggdWOlpKLy2n-pUSLcacp6wNsF6rF7G4GrcKJ37yQVUXyaXrnLyJ7ObgNgSRWOk2R0z_DKpVMXxM12p4NXlU1B6Oz8zc72G1gJIApxkMa1bKsfG-zubPZuYK_3wRHBClibmRgbpbVzGTYcBNDdbreaeMW0LdRKUI_LDqJQdf5y29tJMFPXogZNs7rvXQPlV8d9mc8i0aaO1kwIFiBiexVEoCObnyopadrRuKyorU2bBVYAXbrYHwFP18hZAkm-H3P5mUqt8q1-yXYZF0qk4Gd_hAn-ePN101jnIjj-7L0VmO8ZU1oiGCswsNAmO_IKT7j7c4PG2wSFnHLwYR5bxvPKEDh5NmW6DZlPtL4BsdeW-Z1z93hIw923BWfVCldKvL_E4KYNYa9Wcu-D3e3wMSWvfph_-UsmbIJeQeqQEX3Mz2s78Y98ETAQFLqocZBAqZtGQ-UVYMXZlu6-_LI5REVlvW0REuV04zdPXiDWoxu_Fr-G4XqkBusryxhMvSqmu_CCTCrSnRV2Veu8jHTsUMFBoQ3gIhOz6DRT9N1LhbJv4_0L6Vjw6zGpfSMOeEyCD34IInuhUyAUYU-PQkxYHyqCYXPPSqxJVDl5Bia1OFDHITu4rU4A"
                }
            },
            "flow": "hpp",
            "hpp_url": "https://pay.psp.name/redirect/hpp/?cpi=cpi_Y8Puis4vtNjAYZwb",
            "payment_flow": "charge",
            "created": 1597833098,
            "updated": 1597833098,
            "payload": null,
            "description": "Invoice Example",
            "descriptor": null,
            "callback_url": "https://example.com",
            "return_url": "https://example.com",
            "original_data": {
                "external_id": null,
                "merchant_id": null,
                "provider_id": null,
                "external_mid": "org_02HJ5jTUtan8ZXaT",
                "provider_code": null
            },
            "rrn": null,
            "approval_code": null,
            "reserved_amount": null,
            "reserve_expires": null,
            "unreserved": null,
            "source": "merchant_api",
            "callback_logs": []
        },
        "relationships": {
            "payment-service": {
                "data": {
                    "type": "payment-services",
                    "id": "payment_card_usd_hpp"
                }
            },
            "payment-method": {
                "data": {
                    "type": "payment-methods",
                    "id": "payment_card"
                }
            },
            "customer": {
                "data": {
                    "type": "customers",
                    "id": "cus_Tjhe1ufEB3kRrgWy"
                }
            }
        },
        "links": {
            "self": "/api/payment-invoices/cpi_HeSWMM9LvQonCcQc"
        }
    }
}

Note

Есть 2 основных способа перенаправления пользователя на платёжную страницу:

Использовать flow_data для формирования html формы: action формы => action, method формы => method скрытые параметры формы => params (если есть в ответе).
Использовать hpp_url: перенаправить пользователя на указанный URL (метод GET).

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

Note

Статусы инвойсов описаны в Руководствах. Коды состояния HTTP, используемые API в ответах на запросы, описаны ниже.

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

API: PUBLIC

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

Endpoint: /payment-invoices/{id}

Method: GET

Пример ответа (JSON)

{
    "data": {
        "id": "cpi_HeSWMM9LvQonCcQc",
        "serial_number": "HeSWMM9LvQonCcQc",
        "created": 1597833098,
        "test_mode": true,
        "reference_id": "70d42236-2cc4-4e26-8f2f-987fd8fbc276",
        "currency": "USD",
        "amount": 100,
        "payment_amount": 100,
        "processed_amount": 100,
        "refunded_amount": null,
        "description": "Invoice Example",
        "has_return_url": true,
        "status": "processed",
        "resolution": "OK",
        "service": "payment_card_usd_hpp",
        "service_method": "payment_card",
        "service_flow": "hpp",
        "service_currency": "USD",
        "metadata": {
            "key": "value",
            "merchant_url": "https://lets.doc.it"
        },
        "active_payment": {
            "payload": {
                "action": "https://cardgate-staging.psp.name/hpp/cgi_G0bsyhroZj802zQU",
                "method": "GET",
                "params": [],
                "metadata": {
                    "sid": "cgi_G0bsyhroZj802zQU",
                    "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzUxMiJ9.eyJzaWQiOiJjZ2lfRzBic3locm9aajgwMnpRVSIsImV4cCI6MTU5NzgzNDg5OH0.Vsjj8tcnKqFrxz5SynNdC0q8x_eQawJG9CJTAEUNm6JQG64En4zYij_DjggdWOlpKLy2n-pUSLcacp6wNsF6rF7G4GrcKJ37yQVUXyaXrnLyJ7ObgNgSRWOk2R0z_DKpVMXxM12p4NXlU1B6Oz8zc72G1gJIApxkMa1bKsfG-zubPZuYK_3wRHBClibmRgbpbVzGTYcBNDdbreaeMW0LdRKUI_LDqJQdf5y29tJMFPXogZNs7rvXQPlV8d9mc8i0aaO1kwIFiBiexVEoCObnyopadrRuKyorU2bBVYAXbrYHwFP18hZAkm-H3P5mUqt8q1-yXYZF0qk4Gd_hAn-ePN101jnIjj-7L0VmO8ZU1oiGCswsNAmO_IKT7j7c4PG2wSFnHLwYR5bxvPKEDh5NmW6DZlPtL4BsdeW-Z1z93hIw923BWfVCldKvL_E4KYNYa9Wcu-D3e3wMSWvfph_-UsmbIJeQeqQEX3Mz2s78Y98ETAQFLqocZBAqZtGQ-UVYMXZlu6-_LI5REVlvW0REuV04zdPXiDWoxu_Fr-G4XqkBusryxhMvSqmu_CCTCrSnRV2Veu8jHTsUMFBoQ3gIhOz6DRT9N1LhbJv4_0L6Vjw6zGpfSMOeEyCD34IInuhUyAUYU-PQkxYHyqCYXPPSqxJVDl5Bia1OFDHITu4rU4A"
                }
            },
            "status": "processed",
            "resolution": "OK"
        }
    }
}

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

API: PRIVATE

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

Endpoint:

/payment-invoices/{id} — для проверки по идентификатору инвойса
/payment-invoices?filter[reference_id]={reference_id} — для проверки по идентификатору заказа мерчанта (reference_id)

Method: GET

Пример ответа (JSON)

{
    "data": {
        "type": "payment-invoices",
        "id": "cpi_HeSWMM9LvQonCcQc",
        "attributes": {
            "serial_number": "HeSWMM9LvQonCcQc",
            "status": "processed",
            "resolution": "ok",
            "moderation_required": false,
            "amount": 100,
            "payment_amount": 100,
            "currency": "USD",
            "service_currency": "USD",
            "reference_id": "70d42236-2cc4-4e26-8f2f-987fd8fbc276",
            "test_mode": true,
            "fee": 0,
            "deposit": 100,
            "processed": 1597833205,
            "processed_amount": 100,
            "refunded_amount": null,
            "processed_fee": 0,
            "processed_deposit": 100,
            "metadata": {
                "key": "value",
                "merchant_url": "https://lets.doc.it"
            },
            "flow_data": {
                "action": "https://cardgate-staging.psp.name/hpp/cgi_G0bsyhroZj802zQU",
                "method": "GET",
                "params": [],
                "metadata": {
                    "sid": "cgi_G0bsyhroZj802zQU",
                    "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzUxMiJ9.eyJzaWQiOiJjZ2lfRzBic3locm9aajgwMnpRVSIsImV4cCI6MTU5NzgzNDg5OH0.Vsjj8tcnKqFrxz5SynNdC0q8x_eQawJG9CJTAEUNm6JQG64En4zYij_DjggdWOlpKLy2n-pUSLcacp6wNsF6rF7G4GrcKJ37yQVUXyaXrnLyJ7ObgNgSRWOk2R0z_DKpVMXxM12p4NXlU1B6Oz8zc72G1gJIApxkMa1bKsfG-zubPZuYK_3wRHBClibmRgbpbVzGTYcBNDdbreaeMW0LdRKUI_LDqJQdf5y29tJMFPXogZNs7rvXQPlV8d9mc8i0aaO1kwIFiBiexVEoCObnyopadrRuKyorU2bBVYAXbrYHwFP18hZAkm-H3P5mUqt8q1-yXYZF0qk4Gd_hAn-ePN101jnIjj-7L0VmO8ZU1oiGCswsNAmO_IKT7j7c4PG2wSFnHLwYR5bxvPKEDh5NmW6DZlPtL4BsdeW-Z1z93hIw923BWfVCldKvL_E4KYNYa9Wcu-D3e3wMSWvfph_-UsmbIJeQeqQEX3Mz2s78Y98ETAQFLqocZBAqZtGQ-UVYMXZlu6-_LI5REVlvW0REuV04zdPXiDWoxu_Fr-G4XqkBusryxhMvSqmu_CCTCrSnRV2Veu8jHTsUMFBoQ3gIhOz6DRT9N1LhbJv4_0L6Vjw6zGpfSMOeEyCD34IInuhUyAUYU-PQkxYHyqCYXPPSqxJVDl5Bia1OFDHITu4rU4A"
                }
            },
            "flow": "hpp",
            "payment_flow": "charge",
            "created": 1597833098,
            "updated": 1597833207,
            "payload": {
                "token": null,
                "client_ip": "",
                "payment_card": {
                    "last": "0000",
                    "mask": "512381******0000",
                    "brand": "mastercard",
                    "first": "512381",
                    "holder": null,
                    "network": "mastercard",
                    "expiry_year": "24",
                    "issuer_name": "FIRST DATA CORPORATION",
                    "expiry_month": "12",
                    "issuer_country": "US"
                }
            },
            "description": "Invoice Example",
            "descriptor": null,
            "callback_url": "https://example.com",
            "return_url": "https://example.com",
            "original_data": {
                    "external_id": "cgi_8A8vc28Hr15D8tZ3",
                    "merchant_id": "host2hostTest",
                    "provider_id": null,
                    "external_mid": "org_02HJ5jTUtan8ZXaT",
                    "provider_code": "test"
            },
            "rrn": null,
            "approval_code": null,
            "reserved_amount": null,
            "reserve_expires": null,
            "unreserved": null,
            "source": "merchant_api",
            "callback_logs": {
                "1597833098": {
                    "status": "done",
                    "processed": 1597833099,
                    "response_code": 200,
                    "transaction_status": "process_pending"
                },
                "1597833206": {
                    "status": "done",
                    "processed": 1597833207,
                    "response_code": 200,
                    "transaction_status": "processed"
                }
            }
        },
        "relationships": {
            "payment-service": {
                "data": {
                    "type": "payment-services",
                    "id": "payment_card_usd_hpp"
                }
            },
            "payment-method": {
                "data": {
                    "type": "payment-methods",
                    "id": "payment_card"
                }
            },
            "customer": {
                "data": {
                    "type": "customers",
                    "id": "cus_Tjhe1ufEB3kRrgWy"
                }
            }
        },
        "links": {
            "self": "/api/payment-invoices/cpi_HeSWMM9LvQonCcQc"
        }
    }
}

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

API: PRIVATE

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

Endpoint: /payment-invoices

Method: GET

Пример ответа (JSON)

{
    "meta": {
        "count": 17,
        "size": 20,
        "before": "cpi_o8CBGwATmJag4p32",
        "after": "cpi_HeSWMM9LvQonCcQc"
    },
    "links": {
        "prev": "",
        "next": ""
    },
    "data": [
        {
            "type": "payment-invoices",
            "id": "cpi_HeSWMM9LvQonCcQc",
            "attributes": {
                "serial_number": "HeSWMM9LvQonCcQc",
                "status": "processed",
                "resolution": "ok",
                "moderation_required": false,
                "amount": 100,
                "payment_amount": 100,
                "currency": "USD",
                "service_currency": "USD",
                "reference_id": "70d42236-2cc4-4e26-8f2f-987fd8fbc276",
                "test_mode": true,
                "fee": 0,
                "deposit": 100,
                "processed": 1597833205,
                "processed_amount": 100,
                "refunded_amount": null,
                "processed_fee": 0,
                "processed_deposit": 100,
                "metadata": {
                    "key": "value",
                    "merchant_url": "https://lets.doc.it"
                },
                "flow_data": {
                    "action": "https://cardgate-staging.psp.name/hpp/cgi_G0bsyhroZj802zQU",
                    "method": "GET",
                    "params": [],
                    "metadata": {
                        "sid": "cgi_G0bsyhroZj802zQU",
                        "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzUxMiJ9.eyJzaWQiOiJjZ2lfRzBic3locm9aajgwMnpRVSIsImV4cCI6MTU5NzgzNDg5OH0.Vsjj8tcnKqFrxz5SynNdC0q8x_eQawJG9CJTAEUNm6JQG64En4zYij_DjggdWOlpKLy2n-pUSLcacp6wNsF6rF7G4GrcKJ37yQVUXyaXrnLyJ7ObgNgSRWOk2R0z_DKpVMXxM12p4NXlU1B6Oz8zc72G1gJIApxkMa1bKsfG-zubPZuYK_3wRHBClibmRgbpbVzGTYcBNDdbreaeMW0LdRKUI_LDqJQdf5y29tJMFPXogZNs7rvXQPlV8d9mc8i0aaO1kwIFiBiexVEoCObnyopadrRuKyorU2bBVYAXbrYHwFP18hZAkm-H3P5mUqt8q1-yXYZF0qk4Gd_hAn-ePN101jnIjj-7L0VmO8ZU1oiGCswsNAmO_IKT7j7c4PG2wSFnHLwYR5bxvPKEDh5NmW6DZlPtL4BsdeW-Z1z93hIw923BWfVCldKvL_E4KYNYa9Wcu-D3e3wMSWvfph_-UsmbIJeQeqQEX3Mz2s78Y98ETAQFLqocZBAqZtGQ-UVYMXZlu6-_LI5REVlvW0REuV04zdPXiDWoxu_Fr-G4XqkBusryxhMvSqmu_CCTCrSnRV2Veu8jHTsUMFBoQ3gIhOz6DRT9N1LhbJv4_0L6Vjw6zGpfSMOeEyCD34IInuhUyAUYU-PQkxYHyqCYXPPSqxJVDl5Bia1OFDHITu4rU4A"
                    }
                },
                "flow": "hpp",
                "payment_flow": "charge",
                "created": 1597833098,
                "updated": 1597833207,
                "payload": {
                    "token": null,
                    "client_ip": "",
                    "payment_card": {
                        "last": "0000",
                        "mask": "512381******0000",
                        "brand": "mastercard",
                        "first": "512381",
                        "holder": null,
                        "network": "mastercard",
                        "expiry_year": "24",
                        "issuer_name": "FIRST DATA CORPORATION",
                        "expiry_month": "12",
                        "issuer_country": "US"
                    }
                },
                "description": "Invoice Example",
                "descriptor": null,
                "callback_url": "https://example.com",
                "return_url": "https://example.com",
                "original_data": {
                    "external_id": "cgi_G0bsyhroZj802zQU",
                    "merchant_id": "host2hostTest",
                    "provider_id": null,
                    "external_mid": "ma_aBctkJ3WiRndih0m",
                    "provider_code": "test"
                },
                "rrn": null,
                "approval_code": null,
                "reserved_amount": null,
                "reserve_expires": null,
                "unreserved": null,
                "source": "merchant_api",
                "callback_logs": {
                    "1597833098": {
                        "status": "done",
                        "processed": 1597833099,
                        "response_code": 200,
                        "transaction_status": "process_pending"
                    },
                    "1597833206": {
                        "status": "done",
                        "processed": 1597833207,
                        "response_code": 200,
                        "transaction_status": "processed"
                    }
                }
            },
            "relationships": {
                "payment-service": {
                    "data": {
                        "type": "payment-services",
                        "id": "payment_card_usd_hpp"
                    }
                },
                "payment-method": {
                    "data": {
                        "type": "payment-methods",
                        "id": "payment_card"
                    }
                },
                "customer": {
                    "data": {
                        "type": "customers",
                        "id": "cus_Tjhe1ufEB3kRrgWy"
                    }
                }
            },
            "links": {
                "self": "/api/payment-invoices/cpi_HeSWMM9LvQonCcQc"
            }
        },
        {
            "type": "payment-invoices",
            "id": "cpi_Qtg8wyWcnSYLksFh",
            "attributes": {
                "serial_number": "Qtg8wyWcnSYLksFh",
                "status": "process_failed",
                "resolution": "expired",
                "moderation_required": false,
                "amount": 100,
                "payment_amount": 100,
                "currency": "USD",
                "service_currency": "USD",
                "reference_id": "05233537-7b5c-4cb8-b596-d65ec9671c67",
                "test_mode": true,
                "fee": 0,
                "deposit": 100,
                "processed": null,
                "processed_amount": null,
                "refunded_amount": null,
                "processed_fee": null,
                "processed_deposit": null,
                "metadata": {
                    "key": "value",
                    "merchant_url": "https://lets.doc.it"
                },
                "flow_data": {
                    "action": "https://cardgate-staging.psp.name/hpp/cgi_jYwKJcItnDjnYzZj",
                    "method": "GET",
                    "params": [],
                    "metadata": {
                        "sid": "cgi_jYwKJcItnDjnYzZj",
                        "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzUxMiJ9.eyJzaWQiOiJjZ2lfall3S0pjSXRuRGpuWXpaaiIsImV4cCI6MTU5NzQxODU2Mn0.y9oVZZx9KKdelCNxtY3U9hhWK0R6LIZrQI0w6GvTZamnwU5c1CAJqBydhEQ1v2o5kmrklUZFSlBFjTlKAy3LBUElW4pfZfaEpixgGC7NEtXkYK8lKYJ8cYLJl-S3s2ONcH5_Nhfu5FGdY0iTa8_giLNUgUZxMGnWY6hy29pexBaYr335I7L-lhqAzwhfY-KJH6KpYGOe_-rJgR447TEdABptqlOExGdAk9lS9PS77aJwIodOV1__xbbu0PRPW__L1S06WfDBfUUoaMulbn9-GyyUNbLs-qoADl_amrkxA0qWfs6ylyOAgsARlVUPs-gh2wVtqxHilPdflXZgfPVi9i9UphiquoGQIObOXJqm5CfuStvWxLNVDIOqcx9wbbXWt9i67W0quzVteQUpCDM0EVMR0WZ-j24JEnz2sllD_Lcz0cA22hZXH2b05tPCl30OwTWX0jkBy5ZzzLVYtQnWn-OPaOPoisK9tRdouDGk1UoTvmAJh_RUin1-wXWq9Zv2VXs6XamjR1sIEbj2Vd5IagCmiKyQiLwG7Jek_lbtF-N5e9JzBeAngf-k6UmA-q6RDS-EMdryH2_qfNF3szxUHq-Yz-LVtanxq263DeA7N8ytJGspZq6MzVsMiixPAyZoVf92M0T6rnYYh23hTdJzxzGBVcov_lOb05XCAHpkG4M"
                    }
                },
                "flow": "hpp",
                "payment_flow": "charge",
                "created": 1597416762,
                "updated": 1597418667,
                "payload": null,
                "description": "Invoice Example",
                "descriptor": null,
                "callback_url": "https://example.com",
                "return_url": "https://example.com",
                "original_data": {
                    "external_id": null,
                    "merchant_id": null,
                    "provider_id": null,
                    "external_mid": "org_02Utan8ZXaTHJ5jT",
                    "provider_code": null
                },
                "rrn": null,
                "approval_code": null,
                "reserved_amount": null,
                "reserve_expires": null,
                "unreserved": null,
                "source": "merchant_api",
                "callback_logs": {
                    "1597416763": {
                        "status": "done",
                        "processed": 1597416763,
                        "response_code": 200,
                        "transaction_status": "process_pending"
                    },
                    "1597418666": {
                        "status": "done",
                        "processed": 1597418667,
                        "response_code": 200,
                        "transaction_status": "process_failed"
                    }
                }
            },
            "relationships": {
                "payment-service": {
                    "data": {
                        "type": "payment-services",
                        "id": "payment_card_usd_hpp"
                    }
                },
                "payment-method": {
                    "data": {
                        "type": "payment-methods",
                        "id": "payment_card"
                    }
                },
                "customer": {
                    "data": {
                        "type": "customers",
                        "id": "cus_Tjhe1ufEB3kRrgWy"
                    }
                }
            },
            "links": {
                "self": "/api/payment-invoices/cpi_Qtg8wyWcnSYLksFh"
            }
        }
    ]
}

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

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

401 (unauthorized)

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

404 (not found)

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

405 (incorrect method)

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

422 (validation error)

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

500 (internal server error)

{
    "errors": [
        {
            "status": "internal_error",
            "code": "500",
            "title": "internal_error",
            "detail": "Internal server error."
        }
    ]
}

2xx Успешные¶

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

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

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

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

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

Warning

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

Note

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