Accept Payments with User Redirect to the Checkout Payment Page¶

General interaction scheme¶

The client creates an order on the merchant's website.
To give the client a choice of payment options, the merchant sends a payment pre-request and receives a response from the Paytone platform with a list of available methods.
The merchant displays the list of methods, and the client chooses the convenient way to pay for the order.

You can skip acts 2 and 3

Sending a payment pre-request is unnecessary if the merchant has defined a payment method for the client and creates a payment invoice after the order creation.
The merchant creates a payment invoice using a public or private API. Having received the invoice, Paytone:
- Initiates the transaction on the provider side
- Transmits payment form data to the merchant
- Sends a Callback to the merchant notifying them about successful invoice creation
The merchant redirects the client to the payment provider's page with the form data.
On the provider's page, the client enters details for payment. The provider sends a debit request to the issuer.
If an additional step of payment confirmation is required (3DSecure or another verification type), the provider redirects the user to the verification page. The client confirms the payment, and the issuer obtains the sent data.
The issuer returns the payment results and completes the transaction.
The provider records the transaction status and returns it to the Paytone platform, and Paytone, in turn, forwards the data to the merchant.
The merchant displays the payment status to the client on the website pages.
Paytone sends a Callback to the merchant notifying them of the payment status.
To clarify the transaction status, the merchant can reconcile the payment by ID or get a complete list of invoice data using a private API. Daily transactional reports are also available on the portal.

Payment pre-request¶

Use pre-requests to obtain the list of services available for any particular currency.

The payment pre-request doesn't filter services by the invoice amount because the user can pay in other currency than the given one.

API: PUBLIC

Authentication: live or test Public keys

Endpoint: /payment-prerequest

Method: POST

Samples (JSON)

Request

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

Response

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

Obtain the List of Available Services via Private API¶

Full List of Payment Services¶

API: PRIVATE

Endpoint: /payment-services

Authentication: BasicAuth

Method: GET

Response Sample

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

Obtain Service Data by ID¶

API: PRIVATE

Endpoint: /payment-services/{id}

Authentication: BasicAuth

Method: GET

ID value: from earlier request

Response Sample

{
    "data": {
        "type": "payment-services",
        "id": "comcps_u1xxlHVw1NyeqmjJ",
        "attributes": {
            "service": "payment_card_usd_hpp",
            "service_method"    === "Request Sample": "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"
        }
    }
}

Invoice Initiation¶

Via Public API¶

Common API request¶

API: PUBLIC

Authentication: live or test Public keys

Attention

The public API supports invoicing if the Forbid creation through the Public API option is disabled in commerce payment account settings. (Forbid public access: FALSE).

Settings → Payment options

Payment options

Endpoint: /payment-invoices

Method: POST

Required fields:

public_key — the account's public key
reference_id — the unique identifier of the operation on the merchant side; if you do not specify it, the API generate it itself and send in response
service — the service identifier, for example payment_card_usd_hpp: find a full list of available services in the dashboard or through Private API request
currency — the invoice currency
amount — the invoice amount in the float format, for example: 100.55

An additional field:

description

Samples (JSON)

Request Sample

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

Response Sample

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

To redirect user to the payment page use hpp_url: redirect user directly to provided url (using GET method).

Submitting HTML Form data¶

Checkout Payment Link is a quick and easy solution for accepting payments for which detailed description you can check the related Guides' section.

API: PUBLIC

Authentication: live or test Public keys

Endpoint: /payment-invoices/process

Method: POST

Required fields for HTML form inputs:

public_key — the account's public key
reference_id — the unique identifier of the operation on the merchant side; if you do not specify it, the API generate it itself and send in response
service — the service identifier, for example payment_card_usd_hpp: find a full list of available services in the dashboard or through Private API request
currency — the invoice currency
amount — the invoice amount in the float format, for example: 100.55

Required in some cases:

customer[reference_id] — required attribute if you send the customer object

Process Payment Link (HTML Form)

<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>

Please check the full list of parameters references for Checkout in the related guide

Via Private API¶

API: PRIVATE

Endpoint: /payment-invoices

Authentication: BasicAuth

Method: POST

Required fields:

reference_id — the unique identifier of the operation on the merchant side; if you do not specify it, the API generate it itself and send in response
service — the service identifier, for example payment_card_usd_hpp: find a full list of available services in the dashboard or through Private API request
currency — the invoice currency
amount — the invoice amount in the float format, for example: 100.55

Required in some cases:

flow - specify a type of the invoice. Can have values charge or verify (charge by default)
service_fields — for services that require sending credentials

Example: for bank_transfer_usd_hpp

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

customer[reference_id] — required attribute if you send the customer object

Additional fields:

test_mode — send true for test transactions; it is false by default
description
customer - object contains the client’s basic data and any associated metadata
- reference_id — required attribute for the customer object in the request
- name
- email
- phone
- individual_tax_id
- date_of_birth
- metadata - for the customer object
- address - object for customer's address data
  - country
  - region
  - city
  - street
  - full_address
  - post_code
metadata - for the Invoice
return_url — a common URL for user return after payment
return_urls — the object with 3 different URLs for user return after payment based on payment status
- success
- fail
- pending — required attribute for the return_urls object in the request
callback_url — URL to send Callbacks when the transaction status changes
gateway_options — gateway modification options, for example, modifying the Checkout page (we need to specify the set and possible values for each account)
expires — date and time of the invoice expiry in Datetime format; the expiry limit is between 14 minutes and 2 days from the date of the invoice creation

Samples (JSON)

Request Sample

{
    "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":"[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",
            "expires": "2020-12-13T15:52:00+00:00"
            }
        }
    }

Response Sample

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

There are 2 ways to redirect user to the payment page:

Use flow_data to build html form: form action => action, form method => method form hidden parameters => params (if present in response).
Use hpp_url: redirect user directly to provided url (using GET method).

Reconciliation by ID¶

Note

Read about invoice statuses in the Guides. Read below about the HTTP status codes used in the API responses.

Via Public API¶

API: PUBLIC

Authentication: live or test Public keys

Endpoint: /payment-invoices/{id}

Method: GET

Response Sample

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

Via Private API¶

API: PRIVATE

Endpoints:

/payment-invoices/{id} — to check by Invoice ID
/payment-invoices?filter[reference_id]={reference_id} — to check by Reference ID (reference_id)

Authentication: BasicAuth

Method: GET

Response Sample

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

Get the Full List of Payment Invoices¶

API: PRIVATE

Endpoint: /payment-invoices

Authentication: BasicAuth

Method: GET

Response Sample

{
    "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 status codes used in responses¶

Response examples of error codes and descriptions

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 Successful responses¶

Code	Description
`200 OK`	The request has succeeded, the resource has been fetched
`201 Created`	The POST request has succeeded and a new resource has been created as a result

4xx Client error responses¶

Code	Description	Directives
`400 Bad Request`	The server could not understand the request due to invalid syntax	Request the transaction status (if the correct method is used, but the status request has received an error `404`, you can consider the request unsuccessful and repeat the operation)
`401 Unauthorized`	The client must authenticate itself to get the requested response	Check the authorization data. The request is unsuccessful. The operation was not created on the platform side (if the error occurred during creation, not with other methods).
`403 Forbidden`	The client does not have access rights to the content. Unlike 401, the client's identity is known to the server	Check the authorization data. The request is unsuccessful. The operation was not created on the platform side (if the error occurred during creation, not with other methods)
`404 Not Found`	The endpoint is valid, but the resource itself does not exist	Check the request data: the query specified incorrect method or the transaction does not exist (if the status request is valid)
`405 Method Not Allowed`	The request method is known by the server but has been disabled and cannot be used	The request is unsuccessful. The operation was not created on the platform side (if the error occurred during creation, not with the other methods)
`409 Conflict`	This response is sent when a request conflicts with the current state of the server: an API returns an error message and duplicate request bod	Process the response body with the previously created transaction according to the merchant's business logic
`422 Unprocessable Entity`	The request was well-formed but was unable to be followed due to semantic errors	The request is unsuccessful. The operation was not created on the platform side (if the error occurred during creation, not with the other methods)

5xx Server error responses¶

Code	Description	Directives
`500 Internal Server Error`	The server has encountered a situation that doesn't know how to handle	Check the transaction status. If there is no transaction with this ID on the server, you can request the creation method again
`502 Bad Gateway`	The server got an invalid response while tried to get a response needed to handle the request	Check the transaction status. If there is no transaction with this ID on the server, you can request the creation method again
`503 Service Unavailable`	The server is not ready to handle the request (common cause is the server is down for maintenance or overloaded)	Check the transaction status. If there is no transaction with this ID on the server, you can request the creation method again
`504 Gateway Timeout`	The server cannot get a response in time	Check the transaction status. If there is no transaction with this ID on the server, you can request the creation method again