Accept Payments with User Redirect to the Checkout Payment Page¶
Payment Pre-request via Public API¶
Use pre-requests to obtain the list of services available for any particular currency.
The payment pre-request does not filter services by the invoice amount because the user can pay in other currency than the given one.
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¶
Endpoint: /payment-services
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":false
},
"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":false
},
"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¶
Endpoint: /payment-services/{id}
Method: GET
ID value: from earlier request
Response Sample
{
"data": {
"type": "payment-services",
"id": "comcps_u1xxlHVw1NyeqmjJ",
"attributes": {
"service": "payment_card_usd_hpp",
"service_method": "payment_card",
"service_currency": "USD",
"available": true,
"active": false,
"enabled": true,
"amount_min": 0.01,
"amount_max": 1000000,
"fee_min": 0,
"fee_max": 0,
"fee_rate": 0,
"fee_fix": 0,
"reserve_lifetime": 0,
"reserve_rate": 0,
"currency": "GBP",
"test_mode": false
},
"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¶
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 sideservice— 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"
},
"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"
}
}
}
Via Private API¶
Endpoint: /payment-invoices
Method: POST
Required fields:
reference_id— the unique identifier of the operation on the merchant sideservice— 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 (for example, QIWI-wallet requires a phone number or wallet ID)
Example: for qiwi_usd_hpp
"service_fields": {
"phone": "+380987654321"
}
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 requestnameemailphonemetadata- for thecustomerobject
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":"[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"
}
}
}
{
"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",
"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": [],
"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"
}
}
}
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¶
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¶
Endpoint:
/payment-invoices/{id}— to check by Invoice ID/payment-invoices?filter[reference_id]={reference_id}— to check by Reference ID (reference_id)
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_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"
}
}
}
Get the Full List of Payment Invoices (via Private API)¶
Endpoint: /payment-invoices
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": [],
"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 |