Card networks, like Visa and Mastercard, offer network tokenization services. Network tokens are 16 digit numbers just like raw card numbers. They are unique for each shopper-company pairing, but are different from the shopper's actual card number. Network tokens are different from tokens provided by Adyen to store your shopper's recurring payment details.
This page is about network tokens from card networks like Visa and Mastercard. To learn more about Adyen tokens, go to Tokenization.
We recommend that you use both features (Adyen tokens and network tokens from card networks) together. This limits your PCI scope and takes advantage of the potentially increased authorization rates.
Benefits of using network tokens
When you make payments with network tokens, you can:
- Reduce shopper friction and unnecessary declines, because network tokens are maintained and automatically updated by card networks.
- Have higher authorisation rates, compared to payments made without network tokens.
- Adopt EMVCo's network token standards with minimal integration efforts.
- Increase payment security, because network tokens are protected with a cryptogram.
Implementation options
To make payments with network tokens, you can either:
- Let Adyen provision new network tokens for you, if you do not already collect them from card networks, or,
- Use your existing network tokens, if you are already collecting network tokens from card networks.
Collect and use new network tokens
You don't need to do any additional integration to get the benefits of network tokens if Adyen requests them on your behalf. Contact Support Team to pay with network tokens that we collect from Visa and Mastercard for you.
Optional: Collect retry data
When you let Adyen collect network tokens, you can optionally choose to get information about attempts to retry payments in your payment response. To do so, contact Support Team.
If you include the retry attempts in your /payments response, the additionalData
object will contain:
retry.attempt.acquirer
: The acquirer processing payments on your behalf.retry.attempt.acquirerAccount
: The acquirer account specific to you.retry.attempt.responseCode
: The numeric acquirer response code from the card network for a refused or cancelled payment.retry.attempt.rawResponse
: The details of the raw unmodified response from the acquirer for refused or cancelled transactions.retry.attempt.networkTokenOffered
: Whether the transaction was attempted with or without a network token.
The following examples show the additionalData
object in the payment response that provides the details of an attempt (attempt1
) with a network token, followed immediately by another attempt (attempt2
) with the raw card details or the recurringDetailReference
.
{
...
"additionalData": {
"retry.attempt1.acquirer": "Acquirer",
"retry.attempt1.acquirerAccount": "AcquirerAccount",
"retry.attempt1.responseCode": "7",
"retry.attempt1.rawResponse": "Pickup card, special condition",
"retry.attempt1.networkTokenOffered": "true"
}
}
{
...
"additionalData": {
"retry.attempt2.acquirer": "Acquirer",
"retry.attempt2.acquirerAccount": "AcquirerAccount",
"retry.attempt2.responseCode": "7",
"retry.attempt2.rawResponse": "Pickup card, special condition",
"retry.attempt2.networkTokenOffered": "false"
}
}
As part of the AUTHORISATION notification, the same additionalData
object from the payment response is present as additional information. The result of both payment attempts will be included in the same notification.
Optional: Collect BIN and summary of the network token
When you let Adyen collect network tokens, you can optionally receive the BIN and summary of the network token used. To do so, contact Support Team.
The additionalData
object in the payment response will then contain:
networkToken.bin
: The BIN of the network token.networkToken.tokenSummary
: The last four digits of the network token.
Pay with network tokens not provisioned by Adyen
If you're already collecting network tokens from card networks like Mastercard and Visa, you can use them to make payments with Adyen. You need to send the network token in your /payments request.
Before you begin
Before you start processing payments with network tokens, make sure you enable the relevant fields that will provide you with card details and network token information in the payment response.
To enable the relevant fields:
- Go to Customer Area > Account > API URLs > Additional data settings.
- Enable the following fields:
- Network Transaction Reference
- Card bin
- Card summary
- Click Save configuration.
Make a one-off payment or the first payment in a subscription
-
Make a POST request to /payments, specifying:
paymentMethod.type
: networkTokenpaymentMethod.brand
: visa or mcpaymentMethod.expiryMonth
: The expiry month of the network tokenpaymentMethod.expiryYear
: The expiry year of the network tokenpaymentMethod.holderName
: The name of the cardholder associated with the network token.paymentMethod.number
: The network token you get from the card networks (for example, from Mastercard and Visa).mpiData.directoryResponse
: YmpiData.authenticationResponse
: YmpiData.cavv
: The cryptogram value. This is the cardholder authentication value you get from the issuer.mpiData.eci
: The electronic commerce indicator you get from the issuer.recurringProcessingModel
: CardOnFile, Subscription, or UnscheduledCardOnFile, depending on your business model.shopperInteraction
: Ecommerce.
{ "merchantAccount": "YOUR_MERCHANT_ACCOUNT", "reference": "YOUR_PAYMENT_REFERENCE", "amount": { "currency": "USD", "value": 1000 }, "paymentMethod": { "type": "networkToken", "brand": "visa", "expiryMonth": "08", "expiryYear": "2020", "holderName": "CARDHOLDER_NAME", "number": "666666xxxxxx6666", }, "mpiData":{ "directoryResponse":"Y", "authenticationResponse":"Y", "cavv":"AAEBAwQjSQAAXXXXXXXJYe0BbQA=", "eci":"05" }, "returnUrl": "https://your-company.com/", "shopperReference": "YOUR_SHOPPER_REFERENCE", "recurringProcessingModel":"CardOnFile", "shopperInteraction": "Ecommerce" }
In the /payments response, you can find the networkTxReference
field. You need this value to make subsequent payments.
Make a subsequent payment with a network token
-
Make a POST request to /payments, specifying:
paymentMethod.type
: networkTokenpaymentMethod.brand
: visa or mcpaymentMethod.expiryMonth
: The expiry month of the network tokenpaymentMethod.expiryYear
: The expiry year of the network tokenpaymentMethod.holderName
: The name of the cardholder associated with the network token.paymentMethod.number
: The network token you get from the card networks (for example, from Mastercard and Visa).paymentMethod.networkPaymentReference
: The network token reference. This is the value of thenetworkTxReference
field that you can find in the response of the first payment.recurringProcessingModel
: CardOnFile, Subscription, or UnscheduledCardOnFile. This value must match the value of therecurringProcessingModel
from the first payment.shopperInteraction
: ContAuth.
{ "merchantAccount": "YOUR_MERCHANT_ACCOUNT", "reference": "YOUR_PAYMENT_REFERENCE", "amount": { "currency": "USD", "value": 1000 }, "paymentMethod": { "type": "networkToken", "brand": "visa", "expiryMonth": "08", "expiryYear": "2020", "holderName": "CARDHOLDER_NAME", "number": "666666xxxxxx6666", "networkPaymentReference": "MCC123456789012" }, "returnUrl": "https://your-company.com/", "shopperReference": "YOUR_SHOPPER_REFERENCE", "recurringProcessingModel": "CardOnFile", "shopperInteraction": "ContAuth" }
The
additionalData
object of the payment response has information such as the BIN and summary of the card that was actually charged.