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 Cublox 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, Cublox:
- 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 Cublox platform, and Cublox, in turn, forwards the data to the merchant.
- The merchant displays the payment status to the client on the website pages.
- Cublox 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)
{
"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
Endpoint: /payment-invoices
Method: POST
Required fields:
public_key— the account's public keyreference_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 responseservice— the service identifier, for examplepayment_card_usd_hpp: find a full list of available services in the dashboard or through Private API requestcurrency— the invoice currencyamount— the 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_key— the account's public keyreference_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 responseservice— the service identifier, for examplepayment_card_usd_hpp: find a full list of available services in the dashboard or through Private API requestcurrency— the invoice currencyamount— the invoice amount in the float format, for example:100.55
Required in some cases:
customer[reference_id]— required attribute if you send thecustomerobject
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 responseservice— the service identifier, for examplepayment_card_usd_hpp: find a full list of available services in the dashboard or through Private API requestcurrency— the invoice currencyamount— the invoice amount in the float format, for example:100.55
Required in some cases:
flow- specify a type of the invoice. Can have valueschargeorverify(chargeby 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 thecustomerobject
Additional fields:
test_mode— sendtruefor test transactions; it isfalseby defaultdescriptioncustomer- object contains the client’s basic data and any associated metadatareference_id— required attribute for thecustomerobject in the requestnameemailphoneindividual_tax_iddate_of_birthmetadata- for thecustomerobjectaddress- object for customer's address datacountryregioncitystreetfull_addresspost_code
metadata- for the Invoicereturn_url— a common URL for user return after paymentreturn_urls— the object with 3 different URLs for user return after payment based on payment statussuccessfailpending— required attribute for thereturn_urlsobject in the request
callback_url— URL to send Callbacks when the transaction status changesgateway_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)
{
"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:
-
Use
flow_datato build html form: form action =>action, form method =>methodform 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
{
"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 |