Tokenisation

Securely reference your customer’s payment data.

Use tokenisation to replace the individual card payment details of your customer with a non-identifiable series of numbers and letters, i.e. “tokens”. Substituting sensitive data with random irreversible tokens lets you safely reference your customers’ payment cards without having to store their data. There is no limit to the number of tokens you can assign.

Benefits of tokenisation:

Reduce PCI DSS compliance by limiting the amount of sensitive data that needs protection
Store card payment details to provide one-click payments for repeat customers
Secure your payment processing with tokens that expire when the substituted cards expire

Because tokenisation substitutes rather than data, tokenised data is impossible to decrypt. See this emerchantpay blog article for more information.

Enable tokenisation for a new or existing customer when they make a payment to the emerchantpay payment gateway. Their payment details are saved in a secure token vault and substituted with an irreversible token that is returned as part of the transaction response. In future transactions, reference the token rather than the sensitive card data to reduce your security exposure. Tokenising a card payment allows a returning customer to select the previously used card and enter in only the CVC/CVV code to confirm the payment.

Tokenise payments made with these transaction types:

Tokenisation is available for server-to-server and Web Payment Form (WPF) integrations. Continue reading for more information on how to tokenise your customers’ payment data for each integration.

Tokenisation on the emerchantpay Web Payment Form (WPF)

The emerchantpay Web Payment Form (WPF) provides tokenisation of card payment details that your customer can use in future payments. Because the tokenised data, the token, and the option to use tokenisation are provided as part of a hosted payment page , you do not need to save the token on your servers.

Prerequisites

To proceed with this solution, you must have an emerchantpay merchant account. Apply for a merchant account by filling out and submitting this contact form.

You will be assigned an emerchantpay Account Manager, who will provide you with credentials and assist you with any of emerchantpay’s payment solutions.

Verify that WPF tokenisation is enabled for your account:
1. Log in to your Genesis Merchant Console
2. In the Configuration > Merchants menu, select your account
3. in the Supported features row, locate the Supports WPF tokenization entry:
If the Supports WPF tokenization or other features related to tokenisation are missing, contact emerchantpay support.
A database or storage system is recommended to associate and reference your customers in subsequent transactions

Enable tokenisation of customer card payment details entered in the WPF

To allow your customer to tokenise their card payment details, pass the remember_card parameter with the WPF Create method.

The remember_card parameter passed with the initial Create method request:

  <?xml version=”1.0″ encoding=”UTF-8″?>
  <wpf_payment>
    <transaction_id>119643250547501c79d8295</transaction_id>
    <usage>40208 concert tickets</usage>
    <description>You are about to buy 3 tickets.</description>
    <notification_url>https://www.example.com/notification</notification_url>
    <return_success_url>http://www.example.com/success</return_success_url>
    <return_failure_url>http://www.example.com/failure</return_failure_url>
    <return_cancel_url>http://www.example.com/cancel.html</return_cancel_url>
    <return_pending_url>http://www.example.com/payment-pending.html</return_pending_url>
    <amount>100</amount>
    <currency>USD</currency>
    <customer_email>jsmith@example.com</customer_email>
    <customer_phone>+001234567890</customer_phone>
    <remember_card>true</remember_card>
    <lifetime>60</lifetime>

When your customer enters in their card payment details on the WPF, they can select Save card to save their card for future use: Tokеnisation on the emerchantpay WPF

Even with the remember_card parameter, your customer must select Save card to tokenise their payment details. Sensitive payment data will not be stored if your customer does not select Save card, but they will still be associated with a consumer ID.

Continue reading for how to reference a customer email and associated consumer_id in subsequent transactions.

After the transaction is processed (see Payment flow for the complete transaction flow), the WPF Notification returns a consumer_id that this email address is associated with.

Example of a returned consumer_id in a notification from the emerchantpay gateway:

signature=c5219b3d385e74496b2b48a5497b347e102849f10eacd25b062f823b
&payment_transaction_transaction_type=sale3d
&payment_transaction_terminal_token=e9fd7a957845450fb7ab9dccb498b6e1f6e1e3aa
&payment_transaction_unique_id=bad08183a9ec545daf0f24c48361aa10
&payment_transaction_amount=500
&wpf_transaction_id=mtid201104081447161135536962
&wpf_status=approved
&wpf_unique_id=26aa150ee68b1b2d6758a0e6c44fce4c
&consumer_id=123456
&payment_transaction_token=ee946db8-d7db-4bb7-b608-b65b153e127d
&notification_type=wpf
&eci=05
&payment_transaction_avs_response_code=5I
&payment_transaction_avs_response_text=Response+provided+by+issuer+processor%3B+Address+information+not+verified
&payment_transaction_cvv_result_code=M
&authorization_code=005645
&retrieval_reference_number=016813015184
&scheme_response_code=00
&scheme_transaction_identifier=MCS267BG0
&scheme_settlement_date=1103
&threeds_authentication_flow=payer_authentication
&threeds_target_protocol_version=1
&threeds_concrete_protocol_version=1

emerchantpay recommends that you use a database or storage system to store and associate the consumer_id that is returned with each email address.

Example of a database where you associate a passed customer_email with a returned consumer_id:

Name	customer_email	consumer_id
John Smith	jsmith@example.com	123456
Jennifer J. Morrison	jenniferm@example.com	987654
Narayan Singh	nsingh@example.com	456123

If your customer has selected Save card they will see their stored cards when you pass their associated parameters in subsequent transactions.

Example of creating a subsequent customer transaction with their consumer_id and associated customer_email alongside the remember_card parameter:

  <?xml version=”1.0″ encoding=”UTF-8″?>
  <wpf_payment>
    <transaction_id>119643250547501c79d8295</transaction_id>
    <usage>40208 concert tickets</usage>
    <description>You are about to buy 3 tickets.</description>
    <notification_url>https://www.example.com/notification</notification_url>
    <return_success_url>http://www.example.com/success</return_success_url>
    <return_failure_url>http://www.example.com/failure</return_failure_url>
    <return_cancel_url>http://www.example.com/cancel.html</return_cancel_url>
    <return_pending_url>http://www.example.com/payment-pending.html</return_pending_url>
    <amount>100</amount>
    <currency>USD</currency>
    <consumer_id>123456</consumer_id>
    <customer_email>jsmith@example.com</customer_email>
    <customer_phone>+001234567890</customer_phone>
    <remember_card>true</remember_card>
    <lifetime>60</lifetime>

Even if your customer does not select Save card and a token is not assigned, pass the consumer_id that is associated with the customer_email for each subsequent Create method request.

If your customer has previously saved their card, their card details will be prefilled and they must enter in only the CVC/CVV code to confirm the payment.

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

Tokenisation in a server-to-server integration

In a server-to-server integration, tokenise your customers’ payment details to minimise your security exposure when you send a payment from your server to the emerchantpay payment gateway.

Prerequisites

To proceed with this solution, you must have an emerchantpay merchant account. Apply for a merchant account by filling out and submitting this contact form.

You will be assigned an emerchantpay Account Manager, who will provide you with credentials and assist you with any of emerchantpay’s payment solutions.

Your server must be PCI DSS certified server to:
- Gather raw customer payment data, such as on a form you host on your site
  
  If you have enabled Client-side Encryption for your server, you can gather customer data without being PCI DSS certified.
  See Use the CSE library in your payment form for more information.
- Detokenise a token to reveal the substituted cardholder data
A database or storage system is recommended to associate and reference your customers’ tokens

Tokenise customer card payment details in a server-to-server integration

To tokenise a customer’s card details, pass the remember_card parameter with the transaction request to enable tokenisation of the passed card payment details.

The remember_card parameter passed with the initial transaction request:

<?xml version=”1.0″ encoding=”UTF-8″?>
  <payment_transaction>
    <transaction_type>sale</transaction_type>
    <transaction_id>119643250547501c79d8295</transaction_id>
    <usage>40208 concert tickets</usage>
    <remote_ip>245.253.2.12</remote_ip>
    <amount>100</amount>
    <currency>USD</currency>
    <card_holder>John Smith</card_holder>
    <card_number>4200000000000000</card_number>
    <expiration_month>12</expiration_month>
    <expiration_year>2023</expiration_year>
    <cvv>123</cvv>
    <customer_email>jsmith@example.com</customer_email>
    <customer_phone>+1987987987987</customer_phone>
    <remember_card>true</remember_card>
  </payment_transaction>

After the transaction is processed (see server-to-server for the complete transaction flow), the transaction response provides a consumer_id and token that the provided customer_email is associated with.

Example of a returned consumer_id and token in a transaction response from the emerchantpay gateway:

  <?xml version=”1.0″ encoding=”UTF-8″?>
  <payment_response>
    <transaction_type>authorize</transaction_type>
    <status>approved</status>
    <mode>live</mode>
    <transaction_id>119643250547501c79d8295</transaction_id>
    <unique_id>44177a21403427eb96664a6d7e5d5d48</unique_id>
    <consumer_id>123456</consumer_id>
    <token>ee946db8-d7db-4bb7-b608-b65b153e127d</token>
    <avs_response_code>5I</avs_response_code>
    <avs_response_text>Response provided by issuer processor; Address information not verified</avs_response_text>
    <cvv_result_code>M</cvv_result_code>
    <authorization_code>345678</authorization_code>
    <retrieval_reference_number>016813015184</retrieval_reference_number>
    <response_code>00</response_code>
    <timestamp>2022-07-11T14:12:42Z</timestamp>
    <descriptor>Descriptor one</descriptor>
    <amount>100</amount>
    <currency>USD</currency>
    <sent_to_acquirer>true</sent_to_acquirer>
    <scheme_transaction_identifier>019091214161031</scheme_transaction_identifier>
    <scheme_settlement_date>0712</scheme_settlement_date>
    <scheme_response_code>00</scheme_response_code>
  </payment_response>

To allow a customer to store more than one payment card, a different token is assigned if a different is passed with the same email address.

Be sure to store all tokens returned for a customer_id and customer_email combination. To determine which saved card (token) to use for a returning customer, use the Get card method or reconcile the payment to get the masked cardholder PAN.

Example of a returned masked PAN in the card_number parameter of a response to a get_card_request:

  <?xml version=”1.0″ encoding=”UTF-8″?>
  <get_card_response>
    <status>active</status>
    <token_id>98765</token_id>
    <token_type>uuid</token_type>
    <card_data>
      <card_number>420000…0000</card_number>
      <card_holder>John Smith</card_holder>
      <expiration_month>12</expiration_month>
      <expiration_year>2023</expiration_year>
      <card_brand>visa</card_brand>
    </card_data>
  </get_card_response>

For more information, see Get card.

To reference returning customers, store the email alongside the consumer_id that is returned with the payment result:

With the initial transaction request, store the passed customer_email alongside any optional identifier such as the customer name.
From the payment response, store the returned consumer_id and token alongside the customer email.
Use the Get card method or perform a reconcile to get the masked cardholder PAN. Store the masked PAN alongside the other customer information.

Example of a database where you associate a passed customer_email with returned consumer_id and token(s) and masked PAN:

Name	customer_email	consumer_id	token	masked Pan
John Smith	jsmith@example.com	123456	ee946db8-d7db-4bb7-b608-b65b153e127d	420000…0000
John Smith	jsmith@example.com	123456	jk976jt1-d2db-1oi1-w453-e11m875e533l	480000…9999
Jennifer J. Morrison	jenniferm@example.com	987654	hr946db8-e1ob-3jk7-b860-c45b112e765e	460000…1234
Narayan Singh	nsingh@example.com	456123	oi866db3-o1kk-1es7-e461-v87e643l744b	440000…5678

To use the tokenised payment information in subsequent transactions, pass the consumer_id and customer_email that you have stored for the customer. In order for your customer to select which saved card (token) to use, display the masked PAN to your customer in your payment form. Pass the associated token based on your customers’ selection.

Example of passing the consumer_id, token, and its associated customer_email:

  <?xml version=”1.0″ encoding=”UTF-8″?>
  <payment_transaction>
    <transaction_type>sale</transaction_type>
    <transaction_id>119643250547501c79d8295</transaction_id>
    <usage>40208 concert tickets</usage>
    <remote_ip>123.456.789.0</remote_ip>
    <amount>100</amount>
    <currency>USD</currency>
    <token>ee946db8-d7db-4bb7-b608-b65b153e127d</token>
    <cvv>123</cvv>
    <customer_email>jsmith@example.com</customer_email>
    <customer_phone>+1987987987987</customer_phone>
    <consumer_id>123456</consumer_id>
  </payment_transaction>

If an email address is associated with a consumer ID and the consumer_id parameter is not passed in subsequent transactions, the gateway will not process the payment.

You can manage tokens—including updating, validating, and deleting tokens—using the emerchantpay Tokenization API. Note that your server must be PCI DSS certified to detokenise a token to reveal the substituted cardholder data.