Cards & Wallets · Key concepts

Saving cards for reuse

A card can be saved so that it may be used for new authorisations without the cardholder entering their details again — either because they chose to keep it on file with you, or because you have an agreement to charge them again in the future. Saving and re-using a card is governed by the card schemes' Stored Credentials Framework, which sets out the consent you need to obtain and the data every transaction has to carry.

Transaction initiation

Every transaction has an initiator:

Customer Initiated Transaction (CIT) — the customer is directly involved in the transaction and is giving you the instruction to process the payment.
Merchant Initiated Transaction (MIT) — you process the transaction without the customer's direct involvement. This requires the card to have been saved by an earlier CIT.

Because the cardholder is not present for an MIT, it cannot be authenticated: 3D Secure is never performed on a merchant initiated transaction. The authentication that supports the whole agreement therefore happens on the CIT that saves the card.

Saving a card

To have a card saved so that it can be re-used for new authorisations, you need the cardholder's consent, and that consent must include the conditions under which the card may be re-used. See Displaying the cardholder agreement below for what to tell them and where.

Two things follow from this:

Consent is not required when a card is stored only so that you can refund it.
Sensitive authentication data is never saved. The card security code (CV2/CVV2/CVC2/CID) is never stored, so it is not available on any later transaction taken against the saved card.

How a saved card can be re-used

The agreement you make with the cardholder determines how the saved card may be charged:

Agreement	What it allows
Cardholder initiated card on file	When the customer comes back to buy again, they do not have to re-enter the details of the card they paid with before. Each payment is a CIT.
Merchant initiated unscheduled card on file	The customer permits you to charge their card on an ad-hoc basis — for example, to top up a congestion charge account whenever its balance drops below a threshold.
Recurring continuous authority	You may charge the card on a regular pattern, for a regular amount — for example, a monthly subscription.
Instalment continuous authority	You may charge the card on a regular pattern, for a regular amount, until a total amount has been collected — for example, part payments of a large purchase.

Unscheduled card on file is not possible without a CV2 unless it has been enabled on your account. Contact us if you need to take ad-hoc merchant initiated payments against a saved card.

Recurring and instalment agreements are taken as Repeats, and the repeats themselves can be triggered on a schedule using the Scheduler.

Scheme references

Any transaction that saves a card for reuse generates a scheme reference (also known as the scheme transaction ID or payment network transaction ID), which the acquirer returns to us. That reference is then sent to the acquirer on any authorisation that uses the saved card, and is what ties the later payment back to the agreement the cardholder gave you. We store it and re-present it on your behalf; see How we determine the default attributes of a transaction below.

Stored Credentials Framework

This section gives an overview of the Stored Credentials Framework for Visa and Mastercard, how we have implemented support for it, and how to override our treatment of your transactions if you need to. Read it alongside any information your acquiring bank has given you; if you are not sure how the mandate applies to your business model, consult your acquirer.

Overview of stored credentials

When you (or your agent) process a transaction and store payment credentials for later use, you must:

obtain consent from the cardholder to store their payment details, and establish a clear agreement for how and when they may be re-used
indicate, as part of the transaction authorisation, that the payment credentials are being stored for future reuse
store the scheme reference for that transaction

When a transaction is processed using stored payment credentials, the authorisation must indicate that existing stored credentials are being re-used, and provide the scheme reference corresponding to the initial transaction where those credentials were stored.

This applies both where credentials will be re-used only by direct engagement with the cardholder — such as a cardholder choosing to save their card in a virtual wallet, like the one in our PaySuite payment page, to avoid re-entering the details in future — and where you will use them to process transactions without further cardholder involvement, such as a recurring or instalment agreement.

Storing payment credentials to facilitate refunds and other types of credit, as well as deferred payments with delayed capture, is not considered “storage” for the purpose of the mandate. A payment credential is considered to be re-used only when it is used to process a new payment transaction or account verification.

We will ensure that transactions are processed with the correct indicators; as described below, in most cases we do not need any additional information from you to determine what these are. We will also store and re-present the scheme reference on your behalf, if we have received one.

Displaying the cardholder agreement

You are responsible for establishing a clear agreement with your cardholders as to when their payment credentials will be stored, and how and when they may be re-used. This should normally include:

the basis on which future transactions will be processed without involving the cardholder
the duration of any trial period, introductory offer, or promotional period
transaction amounts and the timing of any subsequent transactions
instructions on how to cancel the agreement and/or any subsequent transactions

Visa requires that this information is shown to cardholders on the same page that is used to collect payment details. The agreement must be presented on every transaction that saves a card.

If you are using the PaySuite payment page, a customer notice may be used for this, and its content can be varied on a per-session basis:

Displaying a basic recurring agreement on the PaySuite payment page

POST /hosted/rest/sessions/{instId}/payments
{
  "transaction": {
      "money": {
          "currency": "GBP",
          "amount": {
              "fixed": "5.99"
          }
      },
      "recurring": true
  },
  "session": {
      "returnUrl": {
          "url": "https://www.example.com"
      }
  },
  "customerNotice": {
      "content": "You agree that we may store your card details and bill them monthly for the amount shown according to our subscription agreement. You can cancel via the <em>Your Subscriptions</em> section of our web site.",
      "locator": "FORM_BOTTOM"
  }
}

How we determine the default attributes of a transaction

We classify transactions by default in a way that we believe caters for the most common use cases. Unless you tell us otherwise, we assume that you are not storing payment credentials in your own system, and so that any credentials you provide us with have been sourced from the cardholder, who has initiated the transaction. Most merchants should not need to override this behaviour.

Initiation

We assume a transaction was customer initiated (CIT) if any of the following apply:

a card security code (CV2/CVV2/CVC2/CID) is provided
a card number (PAN) is provided
a CardLock token is provided
the transaction is processed via the PaySuite payment page
3D Secure is requested, i.e. transactionOptions.do3DSecure = true

Otherwise, we assume the transaction is merchant initiated (MIT). Repeats are always treated as merchant initiated, and 3D Secure is never performed for an MIT.

Storage

We consider a payment credential to be stored if we will be storing it on your behalf and facilitating future transactions, i.e. by providing you with a merchant token to be used in future requests, or by initiating a recurring or instalment sequence. Conversely, we process the transaction as not storing credentials when:

you specify paymentMethod.registered = false
for hosted sessions, you let your customers decide whether their payment method is stored (features.paymentMethodRegistration = optional) and the customer deselects “save my card”

We consider a stored payment credential to be re-used whenever you use one of the available mechanisms to access one, i.e. using a merchant token instead of a card number, or processing a subsequent recurring or instalment transaction with a Repeat.

Agreement

We infer a recurring agreement whenever the standard recurring workflow is in use, i.e. when processing a payment or account verification marked as initial recurring (transaction.recurring = true), or a subsequent recurring transaction with a Repeat. Similarly, we infer an instalment agreement whenever the standard instalment workflow is in use (transaction.instalment = true, or a subsequent instalment Repeat). Otherwise, we infer that the agreement to re-use a stored payment credential is for ad-hoc/unscheduled reuse, subject to a documented agreement with the cardholder.

Scheme reference handling

We return any scheme reference the acquirer returns to us for a given transaction — see Response elements below. When payment credentials are being stored for reuse, we automatically store the reference on your behalf, associated with the credentials in use, and will use it in future unless:

we determine that the reference cannot be re-used, based on acquirer restrictions
you provide a specific reference to be used instead, in paymentMethod.reuse.originalSchemeReference

For existing stored payment credentials where a suitable scheme reference has not already been stored, we will automatically store and reuse a reference once we receive one. For example, existing recurring sequences are enriched with a scheme reference as soon as one arrives.

Overriding stored credential attributes

Where the default classification above is not sufficient — for example, where you have your own card storage in place — API fields are available to override it:

Field	Meaning
transaction.customerInitiated	Whether the transaction was initiated by the cardholder; for example, on your web site, through an app, or as the result of a mail or telephone order.
paymentMethod.reuse.storage	`NEW`, `EXISTING` or `NONE`: whether the credentials for this transaction will be stored, are being re-used, or will not be stored. May not be provided unless customerInitiated is also provided; when that is `false`, the only valid value is `EXISTING`.
paymentMethod.reuse.agreement	`ADHOC`, `RECURRING` or `INSTALMENT`: the agreement under which the stored credentials will be used or are being re-used. Must be provided whenever storage is `NEW` or `EXISTING`, and may not be provided when it is `NONE`. Where credentials may be stored for multiple purposes, use the broadest value possible, i.e. `ADHOC`.
paymentMethod.reuse.originalSchemeReference	The scheme reference corresponding to the transaction that first stored the payment credential, if available. May not be provided unless storage is `EXISTING`.

These fields are only available when processing payments (including deferred payments) or account verification transactions via the API. It is not possible to override this information when using the PaySuite payment page, or on subsequent recurring/instalment transactions submitted with a Repeat.

You are responsible for the accuracy of stored credential details presented in the API. We may override the values you present where that is required to make a valid presentment for authorisation. If an invalid combination is supplied, the request is rejected with response code V100 and a message describing the problem.

Response elements

We return information about payment credential storage and reuse in API responses and notifications, for payment (including deferred payment), account verification and subsequent recurring/instalment (Repeat) transactions. The transaction.customerInitiated and paymentMethod.reuse elements largely mirror the request fields above, populated according to the final classification we determine after taking any overrides into account, with two differences:

Field	Meaning
paymentMethod.reuse.originalSchemeReference	The scheme reference corresponding to the transaction that first stored the payment credential, if available. This reflects any value given in the request; where we have stored and re-used a value on your behalf, it is shown here.
paymentMethod.reuse.receivedSchemeReference	The scheme reference corresponding to the transaction that has been created, if one was received. For the initial storage of payment credentials this is the value we will store and reuse on your behalf when necessary. For transactions that re-use a stored credential, it may or may not differ from originalSchemeReference.