Skip to content

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_id
  • currency
  • amount
  • service
  • gateway_optionscardgate"tokenize":true
  • customer
    • reference_id

Additional fields:

  • test_mode
  • description
  • customer
    • name
    • email
    • phone
    • meta_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

  1. Create an invoice with a card token and linked Customer's reference_id (required)
  2. 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": {
      }
   }
}