Tokenization

Checkout API is integrated with our Tokenization service. Consumers are allowed to save their card details as tokens when completing a Checkout card payment. The saved card can be used in future purchases to support recurring billing and one-click checkout scenarios.

An overview about our Tokenization service can be found in Tokenization guide.

Steps

1. Create a Checkout

Request a checkoutId via API. The checkoutId is valid for the next 30 minutes.

Use the field body.checkout.tokenize to determine whether the card will be tokenized or not. Three values are permitted:

  • false (default): The card is not tokenized.

  • inquire: The customer will be asked to save the card or not. The Checkout form will be display a checkbox next to cards form. The card details will be tokenized only if the customer accepts this checkbox.

  • true: The card is tokenized without customer intervention on the Checkout form.
     Disclaimer: The Checkout customer should always provide consent to tokenize the card.

POST https://stagconnect.acehubpaymentservices.com/Gateway/v3/Checkouts
{
  "header": {
    "businessId": "{{YOUR_BUSINESS_D}}"
  },
  "body": {
    "transaction": {
      "amount": 1,
      "currencyCode": "EUR",
      "authorizationMode": "payment",
      "trackingCode": "{{UNIQUE_ID}}"
    },
    "checkout": {
      "brandIds": [1010, 1020, 1030],
      "returnUrl": "{{REDIRECTION_URL}}",
      "tokenize": "INQUIRE"
    }
  }
}
{
  "result": 2,
  "description": "Pending",
  "header": {
    "requestTimestamp": "2019-01-01T08:00:00Z"
  },
  "body": {
    "checkout": {
      "checkoutId": "{{CHECKOUT_ID}}",
      "redirect": {
        "method": "GET",
        "url": "https://stag.checkout-web.dta.payvision.app/checkouts/{{CHECKOUT_ID}}"
      },
      "brandIds": [1010, 1020, 1030],
      "expirationTime": "2019-01-01T08:30:00Z",
      "tokenize": "INQUIRE"
    },
    "transaction": {
      "amount": 1,
      "currencyCode": "EUR",
      "authorizationMode": "PAYMENT",
      "trackingCode": "{{UNIQUE_ID}}"
    }
  }
}

2. Create the Checkout form

Please refer to our integrations documentation to learn how to integrate the Checkout form into your website.

Checkout example with tokenize=inquireCheckout example with tokenize=inquire

Checkout example with tokenize=inquire

3. Get the payment status

When the customer completes the payment via the Checkout, our system will redirect the customer to the returnUrl (previously sent on the creation request) and checkoutId will be appended in query parameters. Merchants can get the Checkout status via Checkout API.

The token created can be retrieved from the field body.payments[result=0].body.token.token.

GET https://stagconnect.acehubpaymentservices.com/Gateway/v3/Checkouts/{{CHECKOUT_ID}}?businessId={{BUSINESS_ID}}
{
  "result": 0,
  "description": "Completed",
  "header": {
    "requestTimestamp": "2019-01-01T08:02:00Z"
  },
  "body": {
    "payments": [
      {
        "result": 0,
        "description": "Ok",
        "header": {
          "requestTimestamp": "2019-01-01T08:01:00Z",
          "requestCode": "100.379b4d50-5150-4b8b-a51b-0a22e347a18f"
        },
        "body": {
          "card": {
            "approvalCode": "648786",
            "cvvResult": "U",
            "avsResult": "S",
            "expiryMonth": "12",
            "expiryYear": "2030",
            "firstSixDigits": "411111",
            "holderName": "John Doe",
            "lastFourDigits": "1111"
          },
          "transaction": {
            "amount": 1,
            "brandId": 1010,
            "currencyCode": "EUR",
            "action": "payment",
            "id": "{{PAYMENT_ID}}",
            "trackingCode": "{{UNIQUE_ID}}"
          },
          "token": {
            "token": "36dda477-561b-461d-b149-abe21a8a4cd5",
            "displayHint": "************1111"
          }
        }
      }
    ]
  }
}