Tokenisation Integration Guide

Gateway tokenisation allows you to store payment details in exchange for a token. The token replaces the payment details in the transaction request sent to the gateway. This is useful because it is the gateway that handles the payment details collected from the payer - you thereby reduce your PCI compliance obligations. Further, if the token is stored with the payer data, it may be used when the payer returns to make another purchase.

What is a Token?

A token is an identifier of stored payment details. Details can be returned easily when you tokenize them. The token may be used for all subsequent payment transactions to refer to the previously saved payment details.

Tokens are in PAN format and will pass simple card validation rules, so they can be stored in place of credit card numbers. However, their generation is designed to minimize the likelihood that they will be valid card numbers.

Key Benefits

  • Reduces PCI compliance costs as you do not handle or store any payment details.
  • Reduces internal fraud as your staff have limited access to payment details.
  • Allows you to update payment details stored against a token. This is useful when payment details expire/change, or when the payer wishes to change the payment method.
  • It is actually easy to integrate tokens into systems that currently expect card numbers. That is because tokens generated by the system can appear very much like card numbers and pass basic card validation checks.
  • Allows you to retrieve payment details from a token.
  • Offers different options for verifying payment details.
  • Provides flexible options for token management.
  • Allows you to share tokens with other merchants.

Prerequisites

Note: This guide assumes you are using the Hosted Session card capture method.

Creating a Token

Choose Token Generation Strategy

Defines the strategy used to generate a token within this repository.

Random with Luhn

The generated token id is a random number. It begins with a ‘9’, passes a Luhn (Mod-10) check, and excludes known card numbers.

Example Card: 4123 1234 1234 1234

Generated Token: 9471155300808584

Preserve 6.4

When using the Preserve 6.4 token generation method, the gateway will tokenise the card as per below example:

Example Card: 4111 1111 1111 1234

Generated Token: 411111qwerty1234

Merchant-Supplied

The token is supplied by the merchant. Any merchant-supplied token is validated to not be a valid card number - this may refered to as ‘custom tokens’. See below example:

Example Card: 5111 1111 1111 1234

Generated Token: 'MyCustomToken' 

Sending a Token Creation Request

You can use this workflow to create a token by storing payment details against the token. The token will be stored in the token repository as configured on your merchant profile.

Token Operations

There are four REST operations for creating and managing Tokens, their API reference can be found here:

You can perform the following transactions with a token you have created:

Below is an example request and response for Token generation.

(using Hosted Session ID)

Request

HTTP Method: POST

URL: https://test tyro.mtf.gateway.mastercard.com/api/rest/version/57/merchant/YOUR_MERCHANT_ID/token

{
    "session":{
       "id": "SESSIONID00000000001111111111"
    }
}

Response

{
    "repositoryId": "TYRO_TOKENS",
    "result": "SUCCESS",
    "sourceOfFunds": {
        "provided": {
            "card": {
                "brand": "VISA",
                "expiry": "1220",
                "fundingMethod": "CREDIT",
                "number": "412345xxxxxx1234",
                "scheme": "VISA"
            }
        },
        "type": "CARD"
    },
    "status": "VALID",
    "token": "9123456789101112",
    "usage": {
        "lastUpdated": "2020-01-01T22:35:04.661Z",
        "lastUpdatedBy": "YOUR_MERCHANTID",
        "lastUsed": "2020-01-01T22:35:04.664Z"
    },
    "verificationStrategy": "BASIC"
}

Invalid Tokens

Transaction requests using an invalid token are rejected by the gateway.

For an invalid token RETRIEVE_CARD operation response returns status=INVALID.

You can clear an invalid status by updating the payment details stored against the token.

Retrieve Token Update Information

Key parameters are:

  • usage.lastUpdated

Has the date and time when the token was last updated.

  • usage.lastUpdateBy

Should be empty, indicating that the token was not updated by a merchant.

Card Holder Initiated Transactions

A cardholder- initiated transaction is a transaction that is performed with the active participation of the payer - for example an eCommerce transaction on a website where a cardholder enters their details and agrees to paying for goods or services by pressing a submit button.

Initial Transaction

To indicate that the transaction was initiated by the payer, you must set transaction.source to either:

  • INTERNET - A transaction where the cardholder submits their card details in a website or app.

  • MOTO - A transaction where the card details over the phone or through mail order.

The default transaction type if you do not set transaction.source will be INTERNET.

The payer agrees for you to store their payment details for future use, you need to provide the following fields in the initial transaction:

  • sourceOfFunds.type = CARD
  • sourceOfFunds.provided.card. fields or sourceOfFunds.token
  • transaction.source = INTERNET
  • sourceOfFunds.provided.card.storedOnFile: TO_BE_STORED

The below is an example of a transaction performed on a website and the payer has agreed to have thier card stored via a token:

{
"apiOperation": "PAY", 
"order":{
	"amount": "1.00",
	"currency": "AUD"
},
"sourceOfFunds":{
    "provided":{
        "card":{
            "storedOnFile": "TO_BE_STORED"
        }
    },
	"type": "CARD",
  "token": "TOKEN1234567"
},
"transaction":{
    "source": "INTERNET"
}
}

Subsequent Transactions

For subsequent payments initiated by the payer (not by you) and where the payer’s stored payment details are used, you must provide:

  • sourceOfFunds.type = CARD
  • sourceOfFunds.provided.card. fields or sourceOfFunds.token
  • transaction.source = INTERNET
  • sourceOfFunds.provided.card.storedOnFile: STORED

An example request can be found below:

{
"apiOperation": "PAY", 
"order":{
	"amount": "1.00",
	"currency": "AUD"
},
"sourceOfFunds":{
    "provided":{
        "card":{
            "storedOnFile": "STORED"
        }
    },
	"type": "CARD",
  "token": "TOKEN1234567"
},
"transaction":{
    "source": "INTERNET"
}
}

Merchant-Initiated Transactions

A merchant-initiated transaction is a transaction that is performed using stored payment details but without the active participation of the payer.

You may be performing merchant-initiated transactions if you offer:

  • Arrangements where the payer is charged automatically when pre-agreed conditions are met.

In such cases, you will need to enter into an agreement with the payer about these services. The payer must agree that you store their payment details for this purpose and allow you to subsequently initiate payments. The below should also be noted:

  • Agreement details will never be forwarded to the scheme (eg. Visa/Mastercard) but will be recorded.

  • The transaction source will be sent to the scheme (e.g. Visa/Mastercard) and must be set to “MERCHANT”.

When you enter an agreement with the payer that allows you to subsequently submit merchant-initiated payments, you need to provide the following agreement details in the initial transaction:

  • agreement.id

A unique value generated by you to identify a payment agreement with the payer.

  • agreement.type

Indicates the type of commercial agreement that has been established with the payer.

An example transaction payload can be found below:

{
"apiOperation": "PAY", 
"agreement":{
    "id": "1",
    "type": "UNSCHEDULED"
},
"order":{
	"amount": "1.00",
	"currency": "AUD"
},
"sourceOfFunds":{
	"token": "TOKEN12341231"
},
"transaction":{
    "source": "MERCHANT"
}
}

FAQs

What if I do not have an agreement ID?

If you do not have a unique identifier for your agreement with the payer you can:

  • Generate such an agreement ID for the purpose of the interaction with the gateway. You must then store it and submit it to the gateway on all payments in the series, including the cardholder-initiated transaction.

  • Use an existing identifier (one that you are already storing in your system), for example, the order ID for the first payment in the series

What if the PAN for an agreement changes?

The payment details against an agreement may change, for example, if:

  • the payer lost their card and was issued a new card

  • the payer changed their bank

  • the card had insufficient funds and the payer provided other payment details

If card details have changed (except in case of reissue of expired card and card scheme tokens), you must perform a cardholder-initiated transaction using the same Agreement ID to update the payment details/gateway token before performing a merchant-initiated transaction with the new card number.

Depending on your business model, you may choose to create a new agreement.