Card-on-File

Contents

Overview

Card-on-File, also known as Stored Credentials, is where a cardholder authorizes a merchant to store their card details for use in future transactions. This applies to both customer-initiated transactions (CITs), where the customer selects their previously stored card, without needing to enter their payment details again, as well as merchant-initiated transactions (MITs), where the merchant initiates the transaction without the customer being present, such as with recurring payments.

Standard Handling

Nuvei can store and manage a user’s card(s) for you, in which case we handle the stored credentials on your behalf. You simply need to use the userPaymentOptionId field as explained and demonstrated in User Payment Management (tokenization).

Advanced Handling

If you store and manage card credentials in your own system, and choose not to use Nuvei, then you will need to send the storedCredentialsMode field to indicate that the transaction is using stored credentials.

The storedCredentialsMode field is set on the card block, which is on the paymentOption block (paymentOption.card.storedCredentialsMode). You set this field when calling the /openOrder method (or /payment method if you are using server-to-server). Possible values:

  • For the first transaction, in which the card is being stored, storedCredentialsMode needs to be set to “0”
  • For subsequent transactions, in which the stored card is being used, storedCredentialsMode needs to be set to “1”

Some merchants use their customer’s stored credentials to perform “merchant-initiated transactions” (MITs) such as subscriptions and other recurring transactions. The rules set by the card schemes for these type of transactions are detailed in the Merchant-Initiated Payments section.