Tokenization

Tokenization replaces sensitive payment data such as credit card number with a unique identifier or token. Once you obtain a token for card data or a bank account, you can charge transactions on these tokens without having to store the payment data.

This guide describes how you can store the data using our SDK and Server-to-Server API, how you can subsequently use the stored card details for a one-click payment and how to delete stored data.

Supported payment methods to store

Card details

The following card details can be tokenized:

  • card holder,
  • card number,
  • expiration date.

CVV cannot be stored with a token, you can prompt the shopper to re-enter the CVV code for subsequent transaction, if required.

Bank accounts

DIRECTDEBIT_SEPA is available for tokenization, the following details are stored:

  • bank account holder,
  • IBAN.

Virtual accounts

PAYPAL tokens can be used for a payment since version 2.66.0.

Todo Java Script

Storing payment data

SDK provides two options for storing the payment data:

  • Store the data during a payment: When a shopper is checking out for the first time, he has to fill in his complete payment data. Use this option to automatically store his data during the payment for reuse in later transactions.
  • Store the data as stand-alone: If your site provides shoppers with an administrative area where they can register their payment details independent of a checkout-process, this option is for you.

Store the data during a payment

You have two options for achieving this:

1a. Merchant-determined tokenization

During the checkout process you can store the data by adding an additional parameter to the normal prepare checkout request as described in step 1 of the checkout:

createRegistration=true

1b. Shopper-determined tokenization

You can store the data during a payment. Just set the property isTokenizationEnabled to YES for the created payment parameters. It is available for the OPPCardPaymentParams and OPPBankAccountPaymentParams. Then create and submit a transaction as usual.

2. Receive a token along with payment status

Our server will generate token for the passed payment details and return it with the payment status (step 3).
Parameter registrationId is your generated token. Your server is responsible for handling and storing the token.

Here is an example of the Payment Status response:

{
  "id":"8a8294495e295260015e2da4694059a4",
  "registrationId":"8a82944a580a782101581f3a0b4b5ab9",
  "card":{
    "bin":"420000",
    "last4Digits":"0000",
    "holder":"Jane Jones",
    "expiryMonth":"05",
    "expiryYear":"2018"
  },
  "result":{
    "code":"000.100.110",
    "description":"Request successfully processed in 'Merchant in Integrator Test Mode'"
  },
  // ...
}

Store the data as stand-alone

It is also possible to create just a registration separate from any later payment.
A registration-only transaction is basically using the same workflow and parameters as a payment. You just need to update checkout request and use another endpoint when submitting transaction.

1. Prepare checkout

You have to change two parameters in step 1:

  • createRegistration=true has to be sent.
  • paymentType should not be sent.

2. Create and register a transaction

Create a transaction with the collected valid payment parameters. Then register it using OPPPaymentProvider method and implement the callback.

Receive a token with registration status

Request transaction status from your server as it’s described in integration guide.

NOTE: Resource path for registration-only transaction differs from the path for getting payment status.

Parameter id is your generated token. See an example of the Registration Status response below:
{
  "id":"8a82944a580a782101581f3a0b4b5ab9",
  "card":{
    "bin":"420000",
    "last4Digits":"0000",
    "holder":"Jane Jones",
    "expiryMonth":"05",
    "expiryYear":"2018"
  },
  "result":{
    "code":"000.100.110",
    "description":"Request successfully processed in 'Merchant in Integrator Test Mode'"
  },
  // ...
}

Using payment data

1. Prepare checkout with tokens

Add token parameter to the prepared checkout request (step 1). Your server should send shopper’ tokens along with other configuration data such as amount, currency, order type and etc.

Tokens should be sent in the registrations[n].id parameter, where n is a sequence number from zero, incrementing for each shopper’s token. For example, if the shopper has two tokens, you would send registrations[0].id = {first tokenID} and registrations[1].id = {second tokenID}.

You can test this request in the COPYandPAY guide.

2. Submit a transaction with token

Charging a token is quite similar to working with cards. You just need to create OPPTokenPaymentParams instead of OPPCardPaymentParams.

To pass CVV value use another initializer for OPPTokenPaymentParams class:

Then create and submit a transaction with token payment parameters as usual.

NOTE: CVV cannot be stored with a token, you can prompt the shopper to re-enter the CVV code for subsequent transaction, if required. CVV should be provided to the OPPTokenPaymentParams before submitting transaction.

Getting the payment data by token ID

After checkout is created with customer tokens, you can request the stored payment data along with checkout info using SDK API.

Skipping 3D-Secure for stored cards

To skip 3D-Secure authentication for stored cards, your server should send one additional parameter recurringType=REGISTRATION_BASED during Preparing the checkout.

Deleting the stored payment data

Once stored, a token can be deleted using the backend API method. See details in Server-to-Server section.
You will have to expose this API on your server, because authentication data should be sent as parameters.

Note: Android

Storing payment data

SDK provides two options for storing the payment data:

  • Store the data during a payment: When a shopper is checking out for the first time, he has to fill in his complete payment data. Use this option to automatically store his data during the payment for reuse in later transactions.
  • Store the data as stand-alone: If your site provides shoppers with an administrative area where they can register their payment details independent of a checkout-process, this option is for you.

Store the data during a payment

You have two options for achieving this:

1a. Merchant-determined tokenization

During the checkout process you can store the data by adding an additional parameter to the normal prepare checkout request as described in step 1 of the checkout:

createRegistration=true

1b. Shopper-determined tokenization

You can store the data during a payment. Just set the property isTokenizationEnabled to YES for the created payment parameters. It’s available for the CardPaymentParams and BankAccountPaymentParams. Then create and submit a transaction as usual.

2. Receive a token along with payment status

Our server will generate token for the passed payment details and return it with the payment status (step 3).
Parameter registrationId is your generated token. Your server is responsible for handling and storing the token.

Here is an example of the Payment Status response:

{
  "id":"8a8294495e295260015e2da4694059a4",
  "registrationId":"8a82944a580a782101581f3a0b4b5ab9",
  "card":{
    "bin":"420000",
    "last4Digits":"0000",
    "holder":"Jane Jones",
    "expiryMonth":"05",
    "expiryYear":"2018"
  },
  "result":{
    "code":"000.100.110",
    "description":"Request successfully processed in 'Merchant in Integrator Test Mode'"
  },
  // ...
}

Store the data as stand-alone

It is also possible to create just a registration separate from any later payment.
A registration-only transaction is basically using the same workflow and parameters as a payment. You just need to update checkout request and use another endpoint when submitting transaction.

1. Prepare checkout

You have to change two parameters in step 1:

  • createRegistration=true has to be sent.
  • paymentType should not be sent.

2. Create and register a transaction

Create a transaction with the collected payment parameters. Then register it using OPPPaymentProvider method and implement the callback.

Receive a token with registration status

Request transaction status from your server as it’s described in integration guide.

NOTE: Resource path for registration-only transaction differs from the path for getting payment status.

Parameter id is your generated token. See an example of the Registration Status response below:
{
  "id":"8a82944a580a782101581f3a0b4b5ab9",
  "card":{
    "bin":"420000",
    "last4Digits":"0000",
    "holder":"Jane Jones",
    "expiryMonth":"05",
    "expiryYear":"2018"
  },
  "result":{
    "code":"000.100.110",
    "description":"Request successfully processed in 'Merchant in Integrator Test Mode'"
  },
  // ...
}

Using payment data

1. Prepare checkout with tokens

Add token parameter to the prepare checkout request (step 1). Your server should send shoppers’ tokens along with other configuration data such as amount, currency, order type and etc.

Tokens should be sent in the registrations[n].id parameter, where n is a sequence number from zero, incrementing for each shopper’s token. For example, if the shopper has two tokens, you would send registrations[0].id = {first tokenID} and registrations[1].id = {second tokenID}.

You can test this request in the COPYandPAY guide.

2. Submit a transaction with token

Charging a token is quite similar to working with cards. You just need to create TokenPaymentParams instead of CardPaymentParams.

Then create and submit a transaction with token payment parameters as usual.

NOTE: CVV cannot be stored with a token, you can prompt the shopper to re-enter the CVV code for subsequent transaction, if required. CVV should be provided to the TokenPaymentParams before submitting transaction.

Getting the payment data by token ID

After checkout is created with customer tokens, you can request the stored payment data along with checkout info using SDK API.

Skipping 3D-Secure for stored cards

To skip 3D-Secure authentication for stored cards, your server should send one additional parameter recurringType=REGISTRATION_BASED during Preparing the checkout.

Deleting the stored payment data

Once stored, a token can be deleted using the backend API method. See details in Server-to-Server section.
You will have to expose this API on your server, because authentication data should be sent as parameters.