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 valuescharge
orverify
(charge
by 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
— sendtrue
for test transactions; it isfalse
by defaultdescription
customer
- object contains the client’s basic data and any associated metadatareference_id
— required attribute for thecustomer
object in the requestname
email
phone
metadata
- for thecustomer
object
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 statussuccess
fail
pending
— required attribute for thereturn_urls
object 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 |