Visa Stored Credential Framework: Processing Improvements for Vaulted Cards

Update (October 9, 2018): Dates were updated to reflect proper time frame of rollout.

Update (October 25, 2018): Custom subscription logic updated for clarity.

Visa recently announced a framework and new requirements for merchants that store payment methods for future transactions so their customers can check out faster online. The Visa Stored Credential Framework applies to all Visa transactions made with stored payment methods -- regardless of whether they’re processed from Braintree’s Vault or via an external vault. This framework will be rolled out globally over the next few months, starting with Braintree Direct merchants located in the US and APAC regions in October.

Some examples of transactions with stored payment methods include: recurring transactions; standalone non-recurring transactions for a single purchase; and delayed charges.

For merchants, the new framework and requirements are expected to result in higher transaction approval rates. Cardholders are expected to benefit from improved visibility and a better overall experience.

To support these new Visa rules, Braintree will send new indicators for every transaction made with a stored payment method on behalf of most merchants.

*Note, this framework has expanded to Mastercard transactions. For more information, please see Stored Credential Framework: Processing Improvements for Mastercard Payments.

Stored payment method indicators

Let's look at what these new indicators are and how they apply to real life examples. Each transaction in this framework will be identified by:

Who initiated the transaction:


Cardholder actively participates in the transaction.

  • A typical online checkout transaction where the cardholder uses a stored payment method or is storing a payment method for easy retrieval later.
  • One-time use or first-subscription transaction of a stored payment method.


Cardholder does not actively participate and merchant initiates the transaction via the stored payment method. These are transactions where the cardholder has previously given permission to store their payment method.

  • Recurring transaction of a monthly subscription.
  • Unscheduled payment-method-on-file transactions (ex. rental damages, mini bar expenses charged after checkout, account balance top-up charges, etc.).

Transaction history:

Initial transaction:

The first transaction (authorization or verification) that happens with a stored payment method. Visa returns a unique identifier for an initial transaction that Braintree associates with the stored payment method.

Subsequent transaction:

All subsequent transactions with a stored payment method. Braintree passes the Visa unique identifier that was received with the initial transaction with the stored payment method.

What does this mean for merchants?

For merchants who utilize the Braintree Vault, no updates are required -- although some merchants may need to send new values to Braintree. Merchants who do not store payment methods are also unaffected.

All merchants

All merchants will need to review their checkout experience and make sure they obtain cardholder consent that complies with Visa’s storage agreement guidelines, as paraphrased here for your convenience.

Cardholder storage agreement guidelines

Prior to storing credentials for future use, merchants must establish an agreement with the cardholder. Merchants must retain this agreement for the agreed upon time period, so it can be provided to the issuer upon request. Merchants must also provide the customer a copy of the agreement, where applicable by law.

Basic agreement requirements

  • Truncated version of the stored credentials (i.e., last four digits of card)
  • How the cardholder will be notified of any changes to the consent agreement
  • The expiration date of the consent agreement, if applicable
  • How the stored credential will be used

Additional agreement requirements

If the cardholder provides consent for the merchant to generate merchant Initiated transactions, such as subscription payments, the merchant must also provide the following:

  • Cancellation and refund policies
  • Location of merchant
  • Transaction amount or how it will be calculated
  • Convenience fee or surcharge (if permitted and applicable)
  • The frequency (recurring) or event (unscheduled) that will prompt the transaction

Note that stored credential agreements are not retroactively required for existing payment methods stored prior to October 2018. However, if an existing customer updates their payment method after October 2018, the merchant is required to establish a customer agreement for the new stored payment method.

Merchants who use the Braintree Vault

Braintree’s logic will determine which indicators to send to Visa, so in most cases, merchants who use the Braintree vault are not required to make changes to their existing integration. However, there are two scenarios in which merchants will need to send new values to Braintree:

Unscheduled merchant-initiated transactions

If you process unscheduled transactions as part of your business model that are not cardholder initiated, (things like a separate charge that happens after a guest checks out, rental damages, or minibar expense fall under this) you should indicate that the transaction is unscheduled by using the corresponding transaction source.

Custom subscription logic

If you do not use Braintree’s recurring billing but process recurring transactions, you will need to ensure your logic follows one of the following workflows:

  • Verify all cards when storing them in the Braintree Vault, and process all subsequent subscription transactions using "recurring" in the transaction source.

  • If you do not verify cards upon storage, you should flag the first subscription transaction using "recurring_first" in the transaction source. All subsequent subscription transactions should use "recurring" in the transaction source.

Merchants who do not use the Braintree Vault

Merchants who do not use the Braintree Vault will need to send additional fields when creating a transaction to identify when transactions are processed from an external vault. We will provide more information on how to do this in an upcoming blog post.


The new Visa framework is expected to positively affect merchant approval rates. Merchants may see approval rates improve slowly over a period of time as this mandate is universally adopted. If you have any questions about these changes, please contact our Support team.

Tim Whicker Tim is a Product Manager under Braintree's Cards Compliance team. In his free time, he's a tech, music, and design enthusiast. More posts by this author

You Might Also Like