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, alternative payment method (APM) credentials, and other newer forms of APMs.

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 UPO (User Payment Option) record, which is represented by an encrypted userPaymentOptionId token.

UPOs 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.
• APM account details capture (onboarding) for certain specific APM providers, which stores the captured details in UPO records.
• Nuvei also provides advanced server-side User Payment Option APIs for creating and managing UPOs.

Using UPOs in Payments

UPOs 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 UPOs are used:
  • You can present a list of your customer’s previously captured payment methods (UPOs) 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 (UPOs) instead of re-capturing their payment method details.
  • You can send encrypted userPaymentOptionId token of the UPO (payment method) selected by the customer, in a payment request via one of the Nuvei payment platforms.
• 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 User Payment Management (Tokenization), 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 storedCredentialsMode parameter when sending a /payment request (or /openOrder for Web SDK) using these possible values:

• storedCredentialsMode: “0” – For the first time the stored card credentials are used in a payment transaction.
• storedCredentialsMode: “1” – For stored card credentials that were previously used in a payment transaction processed by Nuvei or by another PSP.

Example /payment Request with storedCredentials Class

{
  "sessionToken":"<sessionToken from /getSessionToken>",
  "merchantId":"<your merchantId>",
  "merchantSiteId":"<your merchantSiteId>",
  "clientRequestId":"<unique request ID in your system>",
  "amount":"200",
  "currency":"USD",
  "userTokenId":"<a customer identifier in your system>",
  "clientUniqueId":"<unique transaction ID in your system>",
  "paymentOption":{
    "card":{
      "cardNumber":"4000027891380961",
      "cardHolderName":"John Smith",
      "expirationMonth":"12",
      "expirationYear":"2030",
      "CVV":"217",
      "storedCredentials":{
        "storedCredentialsMode":"1"
      }
    }
  },
  "deviceDetails":{
    "ipAddress":"<customer's IP address>"
  },
  "billingAddress":{
    "email":"[email protected]",
    "country":"US"
  },
  "timeStamp":"<YYYYMMDDHHmmss>",
  "checksum":"<calculated checksum>"
}