Gateway tokenisation

Store cards securely and process repeat payments using emerchantpay-issued tokens.

Introduction

Gateway tokenisation lets you store a customer’s card details securely in emerchantpay’s token vault and use an emerchantpay-issued token in later payments. Instead of storing or resubmitting the card details, you store the token and use it as a reference to the saved payment credential.

Gateway tokens are intended for use within the emerchantpay environment, which resolves the token to the stored card details when it processes a transaction. The token has no meaning outside emerchantpay. Only emerchantpay can resolve it back to the stored card details.

For general information about tokenisation and a comparison of gateway and scheme tokenisation, see Tokenisation. For complete request and response fields, examples, and error codes, see the Tokenisation API reference.

Note: This article assumes that you understand the available tokenisation types and have chosen to implement gateway tokenisation.

Prerequisites

Before you integrate gateway tokenisation:

Contact emerchantpay Support to enable the tokenisation features required for your integration: Tokenize, Validate Token, Update Token, Delete Token and Detokenize.
For a Web Payment Form (WPF) integration, make sure Supports WPF tokenization is enabled.
For a Server-to-server integration, make sure your card-capture environment meets the applicable PCI DSS requirements. You must also meet the applicable PCI DSS and approval requirements before you can Detokenize tokens to retrieve unmasked card data.
- Client-side encryption can reduce the amount of raw card data handled by your server, but you remain responsible for validating the PCI DSS scope of your implementation.
You can use tokenisation with all transaction types accepting cardholder data.

To verify that WPF tokenisation is enabled for your account:

Log in to your Gateway Console.
In the Configuration > Merchants menu, select your account.
In the Supported features row, locate the Supports WPF tokenization entry.

Server-to-server integration

In a Server-to-server integration, you can save a gateway token and use it for subsequent customer-initiated transactions and supported merchant-initiated transactions. Referenced recurring transactions are an exception: they use a reference to the initial transaction instead of resubmitting the token or cardholder details.

You can create a token during a payment or use the standalone Tokenize service to create one without processing a payment.

Each saved card is associated with a consumer through the Consumers API. When you tokenise a card during a customer’s first payment, emerchantpay can create the consumer automatically and return the consumer_id in the payment response. When you use the Tokenize service, an enabled consumer must already exist.

For requests that use an existing consumer, submit the matching consumer_id and email address. Use:

email in Tokenisation API requests
customer_email in Processing API requests

Note: A token can be used only with its associated consumer ID, email address and merchant. Don’t rely on the email address alone to identify an existing consumer.

Both Customer-Initiated Transactions (CITs) and Merchant-Initiated Transactions (MITs) are supported through the Transactions API:

CITs are payments your customer actively initiates, such as completing a purchase at checkout or adding funds to an account.
MITs are payments that you initiate later under a customer’s previous authorisation, such as a subscription renewal. Supported MIT types include:
- Merchant unscheduled: you charge the customer later at an unscheduled time, such as for usage-based or delayed charges.
- Non-referenced recurring: a specialised flow for migrating an existing recurring payment series from another payment gateway without processing a new initial recurring transaction. This flow is supported only by specific acquirers. Contact emerchantpay Support for assistance.
- Referenced recurring: you charge the customer on a recurring schedule and reference the original transaction so that emerchantpay can derive the required credential and linking information.

1. Tokenise the card

Option A: Tokenise during a payment

To save the card while processing an initial transaction, include:

the card details required by the transaction
remember_card set to true
customer_email
consumer_id, when the customer already has a consumer profile

When the transaction is processed, the response and notification return:

consumer_id – the consumer associated with the email address
token – the gateway token for the saved card

Store both values as soon as you receive them and associate them with the customer_email submitted in the payment request. The token is normally a 36-character UUID and uses token_type set to uuid.

Option B: Tokenise without processing a payment/p>

Use the Tokenize service when you need to register a card independently of a payment. An enabled consumer must already exist. If the consumer does not exist, create one using the Create consumer endpoint before tokenising the card. The email address must be unique. If another consumer already uses the same email address, the Create consumer request is rejected.

Include:

email
consumer_id
token_type set to uuid
card_data, with card_number as a minimum
you can also include card_holder, expiration_month, and expiration_year.

CVV/CVC is not accepted and is never stored.

The response returns the token and token_id. Save the plain-text token value immediately and associate it with the consumer_id and email used in the request.

After the token has been issued, you cannot request the same value again. Tokenising the same card data again creates a new token rather than returning the existing one.

2. Store and present saved payment methods

For each saved card, store a separate record containing:

your customer reference
customer_email
consumer_id
token
token_type
masked card number

You can also retain non-sensitive display information such as the card brand and expiry month and year.

The following is an example server-to-server saved card mapping:

CUSTOMER	`customer_email`	`consumer_id`	`token`	MASKED CARD NUMBER
John Smith	jsmith@example.com	123456	ee946db8-d7db-4bb7-b608-b65b153e127d	420000…0000
John Smith	jsmith@example.com	123456	f9a4eabe-9d4a-4c3f-8148-5620d8bf57a1	480000…9999
Jennifer Morrison	jenniferm@example.com	456123	84cc98a6-1e01-431b-b086-c45b112e765e	460000…1234

Use the Get card service to retrieve the masked card number and other display information associated with a token. You can also obtain the masked PAN by reconciling the payment associated with the token.

To list a consumer’s saved cards, use the Get consumer cards service. It returns non-expired cards with their masked card numbers, cardholder names, expiry dates and card brands. However, the response does not include the gateway token for each card. You must therefore maintain your own mapping between each saved card and its corresponding token so that you can identify which token to submit when the customer selects a saved payment method.

Display only non-sensitive details, such as the card brand and last four digits, when asking a customer to choose a saved card. When the customer selects a card, submit the corresponding token together with the matching consumer_id and customer_email.

A consumer can have multiple gateway tokens. When you tokenise another card for the same consumer, emerchantpay issues a separate token for that card. Keep each token as a separate saved payment method.

3. Process customer-initiated transactions

For a subsequent customer-initiated transaction (CIT), send the following:

token
consumer_id
customer_email
CVV/CVC when required by the terminal or transaction flow

Don’t include token and remember_card in the same transaction request. These parameters are mutually exclusive. Use remember_card set to true when tokenising card details during a payment, or token when processing a payment with an existing saved card.

For gateway tokens, credential_on_file is optional in customer-initiated transactions. The gateway determines its value automatically based on the token’s payment history:

initial_customer_initiated – Until the first payment using the token is approved.
subsequent_customer_initiated – After the first payment using the token is approved.

If you submit either value, the gateway overrides it with the value determined from the token’s state. For merchant-unscheduled transactions, you must set credential_on_file to merchant_unscheduled.

Use 3D Secure when required by your regulatory, risk, or acquiring setup. A gateway token replaces stored card details; it does not authenticate the customer or remove Strong Customer Authentication requirements.

A token can represent all supported cardholder fields or only a subset. If the token contains only the PAN, include the remaining required cardholder and expiry fields in the payment request.

After the initial CIT is approved, retain any returned unique_id, scheme_transaction_identifier and scheme_settlement_date and scheme_transaction_link_id values that you may need to link later merchant-initiated transactions. For Mastercard transactions, scheme_transaction_link_id can be used as the optional credential_on_file_transaction_link_id in a subsequent merchant-initiated transaction. The values you submit depend on the MIT type.

4. Process merchant-initiated transactions

Merchant-initiated transactions (MITs) must follow the request requirements for the selected MIT type. Merchant-unscheduled and non-referenced recurring transactions can use a gateway token together with the associated consumer details. Referenced recurring transactions instead use a reference to the initial transaction and omit the token, card and consumer data.

Don’t store or submit CVV/CVC for a merchant-initiated transaction.

Use the following fields for each MIT type:

USE CASE	REQUIRED LINKING INFORMATION
Merchant unscheduled	Send `token`, `consumer_id` and `customer_email`. Set `credential_on_file` to `merchant_unscheduled`. Set `credential_on_file_transaction_identifier` to the `scheme_transaction_identifier` of the initial CIT. For Mastercard or Maestro, set `credential_on_file_settlement_date` to the `scheme_settlement_date` of the initial CIT. For Mastercard, optionally set `credential_on_file_transaction_link_id` to the `scheme_transaction_link_id` of the initial CIT.
Non-referenced recurring	Use Sale or Authorize with `recurring_type` set to `subsequent`. Send `token`, `consumer_id` and `customer_email`. Set `credential_on_file_transaction_identifier` to the scheme transaction identifier of the original CIT (15 characters for Visa; 9–12 characters for Mastercard or Maestro). For Mastercard or Maestro, set `credential_on_file_settlement_date` to the scheme settlement date of the original CIT. For Mastercard, optionally set `credential_on_file_transaction_link_id` to the scheme transaction link ID of the original CIT. This flow is available only for specific acquirers. Contact emerchantpay Support before using it.
Referenced recurring	Set `recurring_type` to `subsequent`. Set `reference_id` to the `unique_id` of the initial recurring transaction. Do not submit card or cardholder data, `token`, `consumer_id` or `customer_email`. The gateway retrieves the necessary payment credentials and linking information from the referenced transaction.

For the complete stored-credential rules and supported transaction types, see the credential-on-file documentation and the relevant transaction reference.

Web Payment Form integration

With the Web Payment Form (WPF), emerchantpay hosts the checkout page and captures card data on its own PCI DSS-compliant infrastructure. Because the tokenised data, the token, and the option to use tokenisation are provided as part of a hosted payment page, you don’t need to save the token on your servers.

Saved cards are associated with a consumer through the Consumers API. When the customer already has a consumer profile, submit the matching consumer_id and customer_email in the WPF Create request. Don’t rely on customer_email alone to identify an existing consumer.

1. Tokenise the card

In the initial WPF Create request, include:

remember_card set to true
customer_email
consumer_id, when the customer already has a consumer profile
any other fields required by your payment flow

When remember_card is true, the WPF displays the Save card option. The customer must actively select Save card before the card details are tokenised. Don’t treat remember_card as customer consent by itself.

The WPF Create API response returns the consumer_id associated with the customer_email. The consumer_id is also available in the WPF Reconcile response.

When the customer selects Save card and tokenisation occurs, the WPF notification returns payment_transaction_token, which contains the gateway token for the saved card. The notification also includes consumer_id.

A gateway token can be returned even when the payment is declined. Therefore, don’t assume that a token is generated only after a successful payment. Check the WPF notification for payment_transaction_token regardless of the transaction status and store it if required by your integration.

If the customer does not select Save card, no tokenised payment credential is stored. The notification still returns a consumer_id; submit it with the same customer_email in each following WPF request.

2. Store and present saved payment methods

At minimum, store the returned consumer_id with the customer_email submitted in the WPF Create request.

The following is an example WPF consumer mapping:

CUSTOMER	`customer_email`	`consumer_id`
John Smith	jsmith@example.com	123456
Jennifer Morrison	jenniferm@example.com	456123

Also store the payment_transaction_token when you need to:

use the saved card in a server-to-server transaction
manage or delete a specific saved card through the Tokenisation API
keep your own record of the customer’s saved payment methods

3. Process subsequent customer-initiated transactions

For a returning customer, include the following in the WPF Create request:

remember_card set to true
customer_email
consumer_id

The WPF uses the matching consumer_id and customer_email to retrieve and display the cards saved for the consumer. You don’t need to submit an individual token.

The WPF displays the consumer’s saved cards by card brand and last four digits. It automatically preselects the default saved card or, if no default card is configured, the first saved card. The customer can use the preselected card, select another saved card, or choose a different payment method.

The WPF does not prefill the card-entry fields with the saved card details. When the customer submits a payment using a saved card, the WPF resolves the stored card details from the associated token and uses them to process the transaction. The customer must enter the CVV/CVC if required by the transaction flow and may also need to complete 3D Secure authentication.

For more information, see How to tokenize cardholder data in WPF API.

Manage gateway tokens

All Tokenisation API management requests require the following values for the consumer and saved card being managed:

consumer_id
email
token
token_type set to uuid

Always submit the matching consumer_id and email. If the email address belongs to an existing consumer but the matching consumer_id is omitted, the gateway does not process the request.

Use the following services to manage a saved payment method:

SERVICE	PURPOSE
Validate Token	Check whether a token is active and belongs to the expected merchant and consumer context.
Get card	Retrieve masked card details for display or identification.
Update Token	Update supported stored card data, such as the cardholder name or expiry date. The PAN cannot be changed.
Delete Token	Permanently remove the token and its stored payment method.
Detokenize	Retrieve the underlying unmasked card data. Access is restricted and should be used only when explicitly enabled and when the applicable PCI DSS and approval requirements are met.
Retokenize	Attach a scheme-generated token (DPAN) to an existing gateway token.

When a customer removes a saved card, send a Delete Token request and, after a successful response, remove the token from your own saved-payment-method records. Don’t submit a deleted token in later transactions.

Gateway tokens are subject to the expiry date stored for the card and don’t receive the scheme-managed lifecycle updates available with scheme tokenisation.

To attach a scheme-generated token (DPAN) to an existing gateway token, use the Retokenize service. This associates the existing gateway token with a scheme token rather than creating an unrelated gateway token.

If the PAN remains the same and supported card details, such as the expiry date, change, use Update Token. If the PAN changes, create a new token and delete the obsolete token after your migration or customer-confirmation flow is complete.

Import tokens from another provider

You can migrate existing non-network tokens and their associated card details from another payment provider into emerchantpay. The import process uses an encrypted CSV file transferred through SFTP.

The input CSV file must contain the following required fields: token, card_number, card_holder, expiration_month, expiration_year and email.

After processing, emerchantpay provides a response CSV file containing the original token (old_token), the newly generated gateway token (token), consumer_id, token_id, token_type and status.

Because the import file contains sensitive card data, follow the prescribed GPG encryption and secure-transfer process. Contact emerchantpay Support before starting a migration.

Note: This process is for gateway or provider tokens backed by card data. It is not an import flow for card-scheme tokens.

emerchantpay also supports exporting tokenised cardholder data to another payment service provider. The receiving provider must be PCI DSS compliant and provide a public GPG key to encrypt the exported data. Only active tokens are eligible for export. Inactive, expired and revoked tokens are excluded. For more information, see Export of tokenized cardholder data.

Frequently asked questions

What format does a gateway token use?

Gateway tokens use token_type set to uuid and are returned as 36-character UUID values, for example ee946db8-d7db-4bb7-b608-b65b153e127d.

Store the token as an opaque string. Don’t parse it or make assumptions based on its contents.

What card data is stored under the token?

The PAN must be included when a token is created. The cardholder name and expiry date can also be stored.

The CVV/CVC is never stored and must be collected again when the payment flow requires it.

Does gateway tokenisation remove PCI DSS or SCA requirements?

No. It reduces the amount of cardholder data you store and can reduce your PCI DSS scope, but it does not eliminate your obligations, particularly where your systems capture or transmit raw card data.

Tokenisation also does not authenticate the customer, so continue to use 3D Secure and the appropriate Strong Customer Authentication flow where required.

Was this page helpful?