Overview
Card schemes generate network tokens to represent a specific payment card and merchant. Tokenization replaces sensitive payment card information – for example, the primary account number (PAN) – with a token, a unique identifier that does not contain sensitive data.
Nuvei natively supports network tokenization, securely gathering network tokens from Visa and Mastercard, storing them, and using them for subsequent authorization with the card schemes, instead of transmitting payment card information. The card schemes then use the tokens for authorization with issuers. Network tokenization also involves using one-time-use cryptograms the card schemes generate and associate with specific transactions, which further enhances security.
Nuvei supports network tokenization and also provides our own Nuvei Gateway (GW) tokenization.
To perform transactions with network tokens, you can use one of the following methods:
- Nuvei provisions and collects the network tokens – Does not require any additional integration by the merchant.
The process seamlessly integrates with your existing payment flow. Nuvei automatically substitutes card details with network tokens as needed. When Nuvei retrieves the network token, the basic tokenization flow is: - The merchant provides the network tokens – Involves integration steps, but enables the merchant to leverage tokens it already has and collects. When the merchant provides the network token, the basic tokenization flow is:
Merchant Benefits
Improved Security
- Aids in meeting industry standards such as PCI DSS by reducing the storage and processing of sensitive payment data such as card details. Tokenization reduces the merchant’s PCI scope.
- Helps prevent fraud as each transaction is protected with a one-time-use cryptogram.
- Tokenized transactions result in fewer chargebacks and disputes, which increases stability and predictability in cash flows, and increases trust between merchants and cardholders.
Improved Approval Rates
- Card scheme networks maintain and automatically update the network tokens.
Reduced processing cost
- Card scheme networks charge a non-tokenized fee for transactions submitted without a network token.
External Network Tokens
Network tokens do not contain sensitive data, allowing the merchant to collect and store them independently. If the merchant has network tokens or is collecting them from the card schemes, the merchant can utilize these tokens to process transactions with Nuvei.
Merchants using server-to-server REST 1.0 integration can provide the network token, cryptogram (if required), and the token’s expiration month and year in the relevant API request.
Cryptogram Requirements
- Client-initiated transactions (CITs) – Cryptograms are required for Sale and Auth transactions, including non-recurring and initial recurring transactions.
- Merchant-initiated transactions (MITs) – Cryptograms are required for Visa Sale and Auth transactions if the merchant is onboarded to AFT.
Payment (Deposit)
When the merchant provides the network token and the cryptogram, include the following in the /payment
request or the /initPayment
request:
card
class containing:expirationMonth
– The token’s expiration month.expirationYear
– The token’s expiration year.externalToken
class containing:networkTokenNumber
networkTokenCryptogram
(optional)
Example Non-3DS /payment
Request
{ "sessionToken": "<sessionToken from /getSessionToken>", "merchantId": "<your merchantId>", "merchantSiteId": "<your merchantSiteId>", "clientRequestId": "<unique request ID in merchant system>", "clientUniqueId": "<unique transaction ID in merchant system>", "amount": "200", "currency": "USD", "paymentOption": { "card": { "expirationMonth": "12", "expirationYear": "2025", "externalToken": { "networkTokenNumber": "4008370896662369", "networkTokenCryptogram": "ejJRWG9SWWRpU7I1M28DelozSXU=" } } }, "billingAddress": { "email": "[email protected]", "country": "US" }, "deviceDetails": { "ipAddress": "<customer's IP address>" }, "timeStamp": "<YYYYMMDDHHmmss>", "checksum": "<calculated checksum>" }
Example 3DS /initPayment
Request
{ "merchantSiteId": "<your merchantSiteId>", "merchantId": "<your merchantId>", "sessionToken": "<sessionToken from /getSessionToken>", "clientRequestId": "<unique request ID in merchant system>", "currency": "USD", "amount": "200", "paymentOption": { "card": { "expirationMonth": "12", "expirationYear": "25", "externalToken": { "networkTokenNumber": "4008370896662369", "networkTokenCryptogram": "ejJRWG9SWWRpU7I1M28DelozSXU=" }, "threeD": { "methodNotificationUrl": "<methodNotificationURL>", "platformType": "01" } } } }
Example 3D-Secure v2 /payment
Request
{ "sessionToken": "<sessionToken from /getSessionToken>", "merchantId": "<your merchantId>", "merchantSiteId": "<your merchantSiteId>", "clientRequestId": "<unique request ID in merchant system>", "timeStamp": "<YYYYMMDDHHmmss>", "checksum": "<calculated checksum>", "currency": "USD", "amount": "200", "relatedTransactionId": "<transactionId returned from initPayment>", "paymentOption": { "card": { "expirationMonth": "12", "expirationYear": "25", "externalToken": { "networkTokenNumber": "4008370896662369", "networkTokenCryptogram": "ejJRWG9SWWRpU7I1M28DelozSXU=" }, "threeD": { "methodCompletionInd": "U", "version": "<3D-Secure version>", "notificationURL": "<notificationURL>", "merchantURL": "<merchantURL>", "platformType": "02", "v2AdditionalParams": { "challengePreference": "01", "deliveryEmail": "<email address>", "deliveryTimeFrame": "03", "giftCardAmount": "1", "giftCardCount": "41", "giftCardCurrency": "USD", "preOrderDate": "20220511", "preOrderPurchaseInd": "02", "reorderItemsInd": "01", "shipIndicator": "06", "rebillExpiry": "20200101", "rebillFrequency": "13", "challengeWindowSize": "05" }, "browserDetails": { "acceptHeader": "text/html,application/xhtml+xml", "ip": "192.168.1.11", "javaEnabled": "TRUE", "javaScriptEnabled": "TRUE", "language": "EN", "colorDepth": "48", "screenHeight": "400", "screenWidth": "600", "timeZone": "0", "userAgent": "Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47" }, "account": { "age": "05", "lastChangeDate": "20190220", "lastChangeInd": "04", "registrationDate": "20190221", "passwordChangeDate": "20190222", "resetInd": "01", "purchasesCount6M": "6", "addCardAttempts24H": "24", "transactionsCount24H": "23", "transactionsCount1Y": "998", "cardSavedDate": "20190223", "cardSavedInd": "02", "addressFirstUseDate": "20190224", "addressFirstUseInd": "03", "nameInd": "02", "suspiciousActivityInd": "01" } } } }, "billingAddress": { "firstName": "John", "lastName": "Smith", "address": "221B Baker Street", "city": "London", "country": "GB", "email": "[email protected]" }, "shippingAddress": { "firstName": "John", "lastName": "Smith", "address": "221B Baker Street", "city": "London", "country": "GB", "email": "[email protected]" }, "deviceDetails": { "ipAddress": "<customer's IP address>" } }
Example 3DS /payment
Request with Liability Shift
{ "sessionToken": "<sessionToken from /getSessionToken>", "merchantId": "<your merchantId>", "merchantSiteId": "<your merchantSiteId>", "clientRequestId": "<unique request ID in merchant system>", "timeStamp": "<YYYYMMDDHHmmss>", "checksum": "<calculated checksum>", "relatedTransactionId": "<transactionId returned from initPayment>", "currency": "USD", "amount": "200", "transactionType": "Auth", "paymentOption": { "card": { "expirationMonth": "12", "expirationYear": "25", "externalToken": { "networkTokenNumber": "4008370896662369", "networkTokenCryptogram": "ejJRWG9SWWRpU7I1M28DelozSXU=" }, "billingAddress": { "firstName": "John", "lastName": "Smith", "address": "22 Main Street", "city": "London", "country": "GB", "email": "[email protected]" }, "deviceDetails": { "ipAddress": "<customer's IP address>" } } } }
Example 3DS /payment
Request – External MPI
{ "sessionToken": "<sessionToken from getSessionToken>", "merchantId": "<your merchantId>", "merchantSiteId": "<your merchantSiteId>", "clientRequestId": "<unique request ID in merchant system>", "amount": "200", "currency": "USD", "clientUniqueId": "<unique transaction ID in merchant system>", "paymentOption": { "card": { "expirationMonth": "12", "expirationYear": "25", "externalToken": { "networkTokenNumber": "4008370896662369", "networkTokenCryptogram": "ejJRWG9SWWRpU7I1M28DelozSXU=" }, "threeD": { "externalMpi": { "eci": "2", "cavv": "ejJRWG9SWWRpU2I1M21DelozSXU=", "dsTransID": "9e6c6e9b-b390-4b11-ada9-0a8f595e8600" } } } }, "billingAddress": { "email": "[email protected]", "country": "US" }, "deviceDetails": { "ipAddress": "<customer's IP address>", "deviceManufacturerIdentifier": "iPhoneX" }, "userDetails": { "country": "US" }, "timeStamp": "<YYYYMMDDHHmmss>", "checksum": "<calculated checksum>" }
Payout (Withdrawal)
When the merchant provides the network token, include the following in the /payout
request:
cardData
class containing:expirationMonth
– The token’s expiration month.expirationYear
– The token’s expiration year.
externalToken
class containing:networkTokenNumber
Example /payout
Request
{ "merchantId": "<your merchantId>", "merchantSiteId": "<your merchantSiteId>", "clientRequestId": "<unique request ID in merchant system>", "clientUniqueId": "<unique transaction ID in merchant system>", "userTokenId": "<unique customer identifier in merchant system>", "cardData": { "expirationMonth": "12", "expirationYear": "25" }, "externalToken": { "networkTokenNumber": "4000020951595032" }, "currency": "USD", "amount": "200", "deviceDetails": { "ipAddress": "<customer's IP address>" }, "customData": "", "timeStamp": "<YYYYMMDDHHmmss>", "checksum": "<calculated checksum>" }
Unreferenced Refund
For information about how to perform a refund with an external network token for transactions that were not settled by Nuvei, see Unreferenced Refunds with an External Token.