Card Payments with Tokenisation¶
Tokenisation¶
To get a card token, you need at least one successful payment from this card with the tokenisation option enabled. After that in Callbacks or by reconciliation, you obtain the token token in payload object along with the card mask and the user's data.
API: PRIVATE
Endpoint: /payment-invoices
Authentication: BasicAuth
Method: POST
Required fields:
reference_idcurrencyamountservicegateway_options→cardgate→"tokenize":truecustomerreference_id
Additional fields:
test_modedescriptioncustomernameemailphonemeta_data
JSON
{
"data":{
"type":"payment-invoices",
"attributes":{
"test_mode":true,
"reference_id":"ORDER1233",
"description":"TEST",
"currency":"USD",
"amount":1,
"customer":{
"reference_id":"my_customer_1",
"name":"John Doe"
},
"service":"payment_card_usd_hpp",
"gateway_options":{
"cardgate":{
"tokenize":true
}
}
}
}
}
{
"payload":{
"client_ip":"",
"payment_card":{
"last":"0000",
"mask":"512381******0000",
"brand":"mastercard",
"first":"512381",
"holder":"John Doe",
"expiry_year":"32",
"issuer_name":"FIRST DATA CORPORATION",
"expiry_month":"12",
"issuer_country":"US"
},
"token":"4c9jHUgeL1SD7g5byDYn9Gc0RC60NN3x"
}
}
Using tokens¶
Card predefining for Checkout Page¶
API: PRIVATE
Endpoint: /payment-invoices
Authentication: BasicAuth
Method: POST
- Create an invoice with a card token and linked Customer's
reference_id(required) - Submit form data with
flow_data
JSON
{
"data":{
"type":"payment-invoices",
"attributes":{
"reference_id":"test_live_recurrent_11",
"amount":100,
"currency":"USD",
"service":"payment_card_usd_hpp",
"flow":"charge",
"test_mode": true,
"description":"Invoice by Token Example",
"token": "4c9jHUgeL1SD7g5byDYn9Gc0RC60NN3x",
"customer":{
"reference_id":"my_customer_1"
}
},
"callback_url":"https://example.com"
}
}
{
"data": {
"type": "payment-invoices",
"id": "cpi_ADzwZTG99f3q3utQ",
"attributes": {
"serial_number": "ADzwZTG99f3q3utQ",
"status": "process_pending",
"resolution": "ok", // clarifies cause of error or unsuccessful status
"moderation_required": false, // Describes whether the operation is on manual moderation. If status is `true`, the operation is blocked for manual moderation
"amount": 1,
"payment_amount": 1,
"currency": "USD",
"service_currency": "USD",
"reference_id": "test_live_recurrent_11",
"test_mode": true,
"fee": 0,
"deposit": 1,
"processed": null,
"processed_amount": null,
"refunded_amount": null,
"processed_fee": null,
"processed_deposit": null,
"metadata": [],
"flow_data": {
"action": "https://cardgate.example.io/hpp/cgi_ZzhRb7xLro7cIf0N",
"method": "GET",
"params": [],
"metadata": {
"sid": "cgi_ZzhRb7xLro7cIf0N"
}
},
"flow": "hpp",
"payment_flow": "charge",
"created": 1585175055,
"updated": 1585175056,
"payload": null,
"description": null,
"descriptor": "DEMO ACC:Order №:test_live_recurrent_11",
"callback_url": "https://example.site/2fac2a84-a905-40fb-bf61-517506e4f3eb",
"return_url": "https://example.io/about-us?myparam=myvalue",
"original_data": null,
"rrn": null,
"approval_code": null
},
"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_kFIAv2l4M9diZGzK"
}
}
},
"links": {
"self": "/api/payment-invoices/cpi_ADzwZTG99f3q3utQ"
}
}
}
Write-off by Token (instant payment, no user involved)¶
Create Payment Invoice¶
API: PRIVATE
Endpoint: /payment-invoices
Authentication: BasicAuth
Method: POST
Create an invoice with a card token and linked Customer's reference_id (required).
JSON
{
"data":{
"type":"payment-invoices",
"attributes":{
"test_mode": true,
"reference_id":"ORDER1233",
"currency":"USD",
"amount":1,
"service":"payment_card_usd_hpp",
"token":"zsmmfyTkG6hn9DdwDhxh69LdQNJgZWk5xMdY7vg",
"customer":{
"reference_id":"my_customer_1"
},
"gateway_options":{
"cardgate":{
"instant":true
}
}
}
}
}
{
"data": {
"type": "payment-invoices",
"id": "cpi_ADzwZTG99f3q3utQ",
"attributes": {
"serial_number": "ADzwZTG99f3q3utQ",
"status": "process_pending",
"resolution": "ok", // clarifies cause of error or unsuccessful status
"moderation_required": false, // Describes whether the operation is on manual moderation. If status is `true`, the operation is blocked for manual moderation
"amount": 1,
"payment_amount": 1,
"currency": "USD",
"service_currency": "USD",
"reference_id": "test_live_recurrent_11",
"test_mode": true,
"fee": 0,
"deposit": 1,
"processed": null,
"processed_amount": null,
"refunded_amount": null,
"processed_fee": null,
"processed_deposit": null,
"metadata": [],
"flow_data": {
"action": "https://cardgate.example.io/hpp/cgi_ZzhRb7xLro7cIf0N",
"method": "GET",
"params": [],
"metadata": {
"sid": "cgi_ZzhRb7xLro7cIf0N",
"token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzUxMiJ9*****"
}
},
"flow": "hpp",
"payment_flow": "charge",
"created": 1585175055,
"updated": 1585175056,
"payload": null,
"description": null,
"descriptor": "DEMO ACC:Order №:test_live_recurrent_11",
"callback_url": "https://example.site/2fac2a84-a905-40fb-bf61-517506e4f3eb",
"return_url": "https://example.io/about-us?myparam=myvalue",
"original_data": null,
"rrn": null,
"approval_code": null
},
"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_kFIAv2l4M9diZGzK"
}
}
},
"links": {
"self": "/api/payment-invoices/cpi_ADzwZTG99f3q3utQ"
}
}
}
Initiate Write-off¶
API: CARDGATE (URL issued by the manager before integration beginning)
Endpoint: /payment/sale
Authentication: bearerToken (send the token parameter from response on request, flow_data object → metadata)
Method: POST
Request Sample (JSON)
{
"data": {
"type": "sale-operation",
"attributes": {
}
}
}