Stored Credential Framework: Introducing External Vault Status

Braintree recently introduced the external vault status field. This field allows merchants utilizing an external vault to benefit from Braintree’s stored credential framework. Merchants utilizing an external vault for card storage can utilize this new field in order to help maximize approval rates for stored cards and maintain payment network compliance.

Here we’ll outline new fields for merchants utilizing an external vault. For more details, please see the Visa Stored Credential Framework: Processing Improvements for Vaulted Cards and Stored Credential Framework: Processing Improvements for Mastercard Payments blog posts.

Braintree Vault

Merchants utilizing the Braintree Vault automatically benefit from the stored credential framework. The rest of this blog post does not apply to Braintree Vault users.

External Vault

An external vault represents a secure credit card storage solution located outside of Braintree (e.g., a third-party vault, not tokenized through Braintree). It’s easy for external vault users to integrate the stored credential framework into their workflow. With only a few additional fields, external vault users can benefit from the stored credential framework, just like merchants using the Braintree Vault.

External vault status values

Braintree introduced two external vault status values. This field allows external vault merchants to flag their transactions so Braintree can pass on the proper stored credential indicators onto the payment networks.


  • This status indicates that, as a result of this transaction succeeding, the payment method will be stored in your external vault.

    • If transacting upon storage, merchants must include ‘will_vault’ in the transaction request to indicate they plan to store the payment method.
    • Note: Merchants must process a successful transaction before storing the payment method.
  • The payment method should only be stored if the ‘will_vault’ transaction receives an approval from the card issuer. This indicates the card issuer will allow the payment method to be stored for subsequent use.


  • By specifying this external vault status, the merchant indicates that the payment method is already stored on behalf of the customer.

Network transaction identifier

The initial ‘will_ vault’ transaction will not only be used to initiate the storage of a payment method, but it may also return a network transaction identifier (NTI) via the ‘network_ transaction_id’ field. The NTI allows issuers to look up the earlier initial transaction when processing a payment using a vaulted payment method. The issuer can then evaluate subsequent payments by referencing the initial transaction. Note: If the card brand does not support NTI, Braintree will return an empty value.

Merchants should store the NTI with the customer’s stored payment method. When processing a subsequent transaction using a stored payment method, merchants should include the external vault status ‘vault’ along with the NTI stored earlier in ‘external_ vault.previous_ network_ transaction_id’.

We recommend that external vault users utilize NTI when processing recurring transactions.


  1. A cardholder presents their card to be stored with a merchant
  2. The merchant specifies the externalvault.status ‘willvault’ in the initial transaction
  3. The initial transaction receives an approval
  4. The merchant stores the card in their external vault
  5. The merchant also stores the network transaction identifier (NTI) with the card
  6. The cardholder returns to make a purchase and selects their stored card
  7. The merchant submits a transaction request using the stored card details, specifies the external_ vault.status ‘vaulted’, and passes the stored NTI in the ‘external_ vault.previous_ network_ transaction_id’ field


The stored credential framework is expected to help improve merchant approval rates, and the external vault status values can benefit merchants utilizing an external vault. 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

    Stay up to date – subscribe to our RSS feed