PCI Vault Logo
Stored Credentials

The VISA Stored Credential Transaction framework is a best-practice framework for storing Payment Card information for future transactions. Even though the Stored Credential Transaction framework is a VISA requirement specifically, it is good practice to be compliant with the framework for all payment cards.

To comply with the Stored Credential Transaction framework, you will need to do the following:

  1. Disclose to the cardholder how their card credentials will be used.
  2. Obtain and store a mandate indicating the cardholder's consent.
  3. Notify the cardholder of any changes to the agreement.
  4. Notify the cardholder that the credentials have been stored, by performing an initial payment or a zero/auth charge.
  5. Submit extra details to your Payment Processor to indicate how the credentials are being used.
  6. Proactively notify the cardholder of future transactions and their ability to cancel the agreement.

PCI Vault can help with the bold items: Storing the mandate, and performing a charge (recurring, initial, or zero/auth).

Storing a Mandate

In most cases, a stored credential will be used by you to initiate transactions. In that case, there are three types of transactions. You need to know which type of transaction you will be using:

Type Description
Instalment A series of payments, at regular intervals, for a single purchase.
Recurring A series of payments, at regular intervals, as per agreement for future goods and services.
Unscheduled A payment at a future agreed-upon date or event, which does not happen at a regular interval. For example: An account auto-top up.

The cardholder consent mandate need to have the following details:

  • The last 4 digits of the card number.
  • Details of how the cardholder will be notified of changes.
  • The agreement's expiry date.
  • Details of how the stored credentials will be used.

If you are going to use the stored credentials to initiate transactions, you will also need to store the following:

  • The amount or details how the amount will be calculated.
  • Any permitted extra charges.
  • The transaction frequency (for recurring transactions).
  • The total purchase amount (for instalment transactions).
  • The terms of future transactions (for instalment transactions).
  • The event that will initiate the transaction (for unscheduled transactions).

There are many ways to store a mandate on PCI Vault. One way is to store the standard parts of the agreement on your own servers, and the non-standard parts on PCI Vault in a JSON object. The two partial data-items can then be merged and processed to display a user-friendly mandate document to the user.

To store JSON object with the non-standard agreement details on PCI Vault, the POST /vault/update can be used to update any exising token with the mandate.

For example, to mark an existing token as a stored credential for instalment transactions, you can POST the following details to /vault/update:

  "mandate": {
    "last_4": "4953",
    "expiry": "2031-12-01",
    "type": "instalment",
    "total_amount": 700000,
    "recurring_amount": 7000

This endpoint will add mandate as a first-level key in the existing encrypted data without changing the associated token.

The GET /vault endpoint can then be used to retrieve mandate information for populating the user-friendly mandate document. Make sure to use the mask_fields argument to prevent the endpoint from returning the full PAN.

Initiating a Charge

When a credential is stored, one of the requirements is to initiate an initial charge, or a zero/auth charge. Any later charges will also be initiated with some extra information being sent through to the PSP. The values and formats of this extra information highly varies between PSPs. Be sure to check your PSP documentation for more information on their requirements.

These extra data fields can be stored either by yourself or by PCI Vault. However, storing them yourself is the more practical option considering that these fields don't contain sensitive information.

Any charge (whether it is the initial charge, zero/auth verification, or any other charge) can be submitted via PCI Vault through the proxy endpoint.

For more information on how to use this endpoint, please check our guide on Proxying Payment Card Data. For a Stripe specific example, please check the Stripe Example guide.