Overview

A (credit/debit) cardholder can authorize a merchant to store their card details for use in future transactions. This is known as Card-on-File (or Stored Credentials).

Nuvei’s User Payment Management

Nuvei can store and manage customer card details (stored credentials) on your behalf (see User Payment Management (Tokenization)). Each stored customer payment method is represented by an encrypted userPaymentOptionId token for use in payment requests.

Payment transactions are initiated in two ways:

• Customer-initiated transactions (CITs) – The customer selects one of their previously stored cards to make a payment, without needing to re-enter their payment details again.
• Merchant-initiated transactions (MITs) – The merchant initiates a transaction without the customer needing to be present, using stored card credentials previously designated by the customer. For example to perform MIT Recurring Payments or Subscriptions.

Handling Stored Credentials Yourself

Only merchants who have 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.

Example /payment Request with storedCredentials Block

{
  "sessionToken":"<sessionToken from getSessionToken>",
  "merchantId":"<your merchantId>",
  "merchantSiteId":"<your merchantSiteId>",
  "clientRequestId":"<unique request ID in your system>",
  "amount":"100",
  "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":"2022",
      "CVV":"217",
      "storedCredentials":{
        "storedCredentialsMode":"1"
      }
    }
  },
  "deviceDetails":{
    "ipAddress":"127.0.0.1"
  },
  "billingAddress":{
    "email":"john.smith@email.com",
    "country":"US"
  },
  "timeStamp":"<YYYYMMDDHHmmss>",
  "checksum":"<calculated checksum>"
}