Overview
Card-on-File (also known as Stored Credentials) allows a customer to authorize you (the merchant) to store their payment method details for use in future transactions. This applies to credit/debit card details, APM credentials (Alternative Payment Methods), and other newer forms of alternative payments.
As you may know, any organization seeking to store sensitive customer payment credentials must comply with the rigorous PCI Certification process and very strict legal requirements.
Instead of attempting to store your customer’s payment credentials on your system, Nuvei has all the required PCI accreditation to allow us to store and manage your customer’s payment credentials, on your behalf.
User Payment Management
Nuvei stores customer payment credentials in a Nuvei payment token record, which is represented by an encrypted paymentTokenId
token.
Payment tokens are created in a number of ways, which include, for example:
- Automatically, upon successful completion of a payment transaction.
- Direct customer input, where your customer captures their payment method details for the current or future transactions.
- Nuvei also provides advanced server-side Payment Token APIs for creating and managing user payment tokens.
Using Payment Tokens in Payments
Payment tokens can be used in a wide variety of ways, as described throughout the documentation.
There are two general types of transactions: CITs and MITs:
- Customer-initiated transactions (CITs) – Transactions initiated by the customer.
These are some CIT-related examples of where payment tokens are used:- You can present a list of your customer’s previously captured payment methods (payment tokens) in a payment method gallery on your payment page.
- The customer’s check-out experience is improved because they simply select one of their previous payment methods (payment tokens) instead of re-capturing their payment method details.
- You can send encrypted
paymentTokenId
of the payment token (payment method) selected by the customer, in a payment request via one of the Nuvei payment platforms.
Example /payment
Request with paymentTokenId
{ "processingEntityId": "<your processingEntityId>", "amount": "10.5", "currency": "USD", "transactionType": "Sale", "paymentOption": { "paymentToken": { "paymentTokenId": "ID of a previously stored payment option" } }, "custom": { "description": "Some description" }, "deviceDetails": { "browser": { "acceptHeader": "Y", "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/105.0.0.0 Safari/537.36", "javaEnabled": "true", "language": "en-US", "colorDepth": "24", "screenHeight": "1080", "screenWidth": "1920", "timeZone": "0", "javaScriptEnabled": "true" } }, "buyerDetails": { "buyerId": "unique customer identifier in your system", "firstName": "John", "lastName": "Smith", "companyName": "Nuvei Corp", "dateOfBirth": "1978-01-01", "email": "[email protected]", "phone": "6175551414", "billingAddress": { "address": "22 Main Street", "zip": "02460", "city": "Boston", "countryCode": "US", "phone": "6175551414", "addressMatch": "true" }, "shippingAddress": { "sameAsBilling": "true", "address": "22 Main Street", "zip": "02460", "city": "Boston", "countryCode": "US", "phone": "6175551414" } }
Example /payment
Response with paymentTokenId
{ "paymentId": "375041", "transactionId": "2110000000010964462", "externalTransactionId": "211010964462", "amount": "10.5", "currency": "USD", "transactionType": "Sale", "result": { "status": "approved" }, "authCode": "966230", "avsCode": "S", "partialApproval": { "requestedAmount": "10.5", "requestedCurrency": "USD" }, "paymentOption": { "card": { "cardHolderName": "John Smith", "maskedCardNumber": "5****6034", "bin": "523233", "last4Digits": "6034", "expirationMonth": "10", "expirationYear": "26", "acquirerId": "99", "cardType": "Credit", "cardBrand": "MASTERCARD", "paymentTokenId": "b058c947-011d-4695-969a-3d6dae9a1d91" } } }
- Merchant-initiated transactions (MITs) – Transactions initiated by the merchant.
The merchant initiates subsequent transactions, with the prior consent of the customer, “without” the customer needing to be “present”.For example, the merchant performs “subsequent” MIT Recurring Payments or Subscriptions, using the stored card credentials previously selected by the customer in the initial transaction.
Storing Credentials Yourself
Only merchants with the relevant level of PCI compliance are allowed to store cardholder credentials. If you have the required PCI level and do not use Nuvei’s payment token management, you may choose to store and manage customer card credentials on your own system. If so, you need to indicate that “stored credentials” are being used in payment transactions to conform to the card schemes’ “Stored Credentials” requirements.
This is done by including a store
parameter when sending a /payment
request using these possible values:
"initial"
– For the first time the stored card credentials are used in a payment transaction."subsequent"
– For stored card credentials that were previously used in a payment transaction.
Example /payment
Request with store
Block
{ "processingEntityId": "<your processingEntityId>", "amount": "10.5", "currency": "USD", "transactionType": "Auth", "paymentOption": { "store": "initial", "card": { "cardNumber": "5101081046006034", "cardHolderName": "John Smith", "expirationMonth": "10", "expirationYear": "2026", "cvv": "345" } }, "custom": { "description": "Some description" }, "deviceDetails": { "browser": { "acceptHeader": "Y", "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/105.0.0.0 Safari/537.36", "javaEnabled": "true", "language": "en-US", "colorDepth": "24", "screenHeight": "1080", "screenWidth": "1920", "timeZone": "0", "javaScriptEnabled": "true" } }, "buyerDetails": { "firstName": "John", "lastName": "Smith", "companyName": "Nuvei Corp", "dateOfBirth": "1978-01-01", "email": "[email protected]", "phone": "6175551414", "billingAddress": { "address": "22 Main Street", "zip": "02460", "city": "Boston", "countryCode": "US", "phone": "6175551414", "addressMatch": "true" }, "shippingAddress": { "sameAsBilling": "true", "address": "22 Main Street", "zip": "02460", "city": "Boston", "countryCode": "US", "phone": "6175551414" } } }