Creating a token

To generate a Token for future use at the same time as submitting a payment, use the createToken object to set a Token up for multiple use (set reusable to "true"). In addition, you can create your own token, send it to us within the object, and set rules as to whether you want to decline payments with duplicate payment details.

To tokenise a payment card separately to a payment, POST the payload to /payment-tokens

If you supply a token value, we will store that, otherwise we'll generate a token value and pass it back to you in the response.

The following JSON documents represent the examples of requests and response for token creation:

  "createToken": {
    "value": "optional - define your own token",
    "reusable": true | false,
    "declineDuplicates": true | false
   }

{
  "requestType": "PaymentCardPaymentTokenizationRequest",
  "paymentCard": {
    "number": "4012000033330026",
    "expiryDate": {
      "month": "12",
      "year": "24"
    }
  },
  "createToken": {
    "reusable": true,
    "declineDuplicates": false
  },
  "accountVerification": false,
  "additionalDetails": {
    "operatorId": "OPERATOR_ID_123XXX",
    "salesSystemId": "W-EU-H3866-FLS2"
  }
}

{
    "clientRequestId": "7ea3415f-62ba-4a1f-8c0f-3c933c1e0c87",
    "apiTraceId": "Y7gIvGrWgLTPAUE7rGOJaQAAAso",
    "requestStatus": "SUCCESS",
    "requestTime": 1673005244065,
    "country": "United Kingdom",
    "paymentToken": {
        "value": "838C36B4-133E-4068-BF50-99008A0DB003",
        "reusable": true,
        "declineDuplicates": false,
        "last4": "0026",
        "brand": "MASTERCARD",
        "type": "PAYMENT_CARD"
    },
    "orderId": "R-e0b9cc9c-730b-4064-b81b-ff84327ce7ac",
    "ipgTransactionId": "84616111269"
}

In the above example, we are allowing our systems to generate a payment token for the given card details, and it sends it back with the value 838C36B4-133E-4068-BF50-99008A0DB003 for later use.

If you wish to set your own value for the token, include the value attribute in the createToken object. If you do not include this, we will define the token value and return it in the response as value attribute in the paymentToken object. If set to true, the token can be reused. If false, it has only a single use.

Updating a token

You can update one or more tokens at a time, and change the settings for the token or the payment card associated with the Token. To make these updates, make a PATCH to /payment-tokens using requestType=PaymentCardPaymentTokenUpdateRequest.

The PaymentTokens object is a list, and can include multiple payment tokens. See the example below to see how to construct the payload. Each of the token objects below includes the updates required - these will automatically be written to the token record on our systems if the request is processed successfully.

{
  "requestType": "PaymentCardPaymentTokenUpdateRequest",
  "paymentTokens": [
    {
      "value": "1751905117310026",
      "reusable": true,
      "declineDuplicates": false,
      "paymentCard": {
        "number": "5424180279791732",
        "expiryDate": {
          "month": "03",
          "year": "27"
        },
        "securityCode": "XXX"
      }
    },
    {
      "value": "9877hkhk68688888ffgh",
      "reusable": true,
      "declineDuplicates": false,
      "paymentCard": {
        "number": "4773410012347324",
        "expiryDate": {
          "month": "12",
          "year": "27"
        },
        "securityCode": "XXX"
      }
    }
  ]
}

{
  "requestStatus": "PARTIAL_SUCCESS",
  "requestTime": "1554308829345",
  "errors": {
    "details": [
      {
        "message": "HOSTED_DATA_ID4773410012347324. Invalid credit card number: CreditCard [cardNumber=4773410...7324, expirationMonth=12, expirationYear=2026"
      },
    ]
  }
}

Using a token

Once the token is created and you have stored it against the customer’s account detail, you can use it to execute payments for the customer. To use a tokenised payment instrument, use the relevant PaymentToken* requestType.

{
  "requestType": "PaymentTokenSaleTransaction",
  "transactionAmount": {
    "total": 12.04,
    "currency": "EUR"
  },
  "paymentMethod": {
    "paymentToken": {
      "value": "1235325235236",
      "function": "DEBIT",
      "securityCode": "977"
    }
  }
}

When a customer is checking out, and you've previously tokenised their payment details mapped to their account, you can request token details to enable the customer to confirm they want to pay with the stored payment instrument.

To do this, use the GET endpoint, providing the tokenid to receive a PaymentTokenDetails response. Our suggestion is you use the last4 value and brand to enable the customer to correctly identify which payment instrument they wish to use, and then from there you can use the token value as in the example above.