Skip to content

Accept Payments with User Redirect to the Checkout Payment Page

General interaction scheme

Redirect to payment page scheme

  1. The client creates an order on the merchant's website.
  2. To give the client a choice of payment options, the merchant sends a payment pre-request and receives a response from the Corefy platform with a list of available methods.
  3. 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.

  4. The merchant creates a payment invoice using a public or private API. Having received the invoice, Corefy:

    • 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
  5. The merchant redirects the client to the payment provider's page with the form data.

  6. On the provider's page, the client enters details for payment. The provider sends a debit request to the issuer.
  7. 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.
  8. The issuer returns the payment results and completes the transaction.
  9. The provider records the transaction status and returns it to the Corefy platform, and Corefy, in turn, forwards the data to the merchant.
  10. The merchant displays the payment status to the client on the website pages.
  11. Corefy sends a Callback to the merchant notifying them of the payment status.
  12. 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)

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

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_keythe 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
  • servicethe service identifier, for example payment_card_usd_hpp: find a full list of available services in the dashboard or through Private API request
  • currencythe invoice currency
  • amountthe invoice amount in the float format, for example: 100.55

An additional field:

  • description

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

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_keythe 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
  • servicethe service identifier, for example payment_card_usd_hpp: find a full list of available services in the dashboard or through Private API request
  • currencythe invoice currency
  • amountthe 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
  • servicethe service identifier, for example payment_card_usd_hpp: find a full list of available services in the dashboard or through Private API request
  • currencythe invoice currency
  • amountthe 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_modesend true for test transactions; it is false by default
  • description
  • customer - object contains the client’s basic data and any associated metadata
    • reference_idrequired 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_urla common URL for user return after payment
  • return_urlsthe object with 3 different URLs for user return after payment based on payment status
    • success
    • fail
    • pendingrequired attribute for the return_urls object in the request
  • callback_urlURL to send Callbacks when the transaction status changes
  • gateway_optionsgateway modification options, for example, modifying the Checkout page (we need to specify the set and possible values for each account)
  • expiresdate 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)

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

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

  1. Use flow_data to build html form: form action => action, form method => method form hidden parameters => params (if present in response).

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

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