Stored Credentials (Card on File)

Merchants may store cardholder credentials, including tokens, for use in future scheduled and unscheduled transactions.

The feature is supported for Visa, Mastercard, Discover, and Amex.

Stored Credentials API fields are optional. If the Stored Credentials fields are submitted, they must be populated with valid values. Otherwise, the transaction may be rejected or processed as a regular credit card transaction.

For Mastercard transactions, credentials must be sent for non-Canadian merchants only. Additional data fields will be ignored if sent for Canadian merchants (the transaction will be processed as a regular credit card transaction and the API fields for Stored Credentials won't be returned in the API response).

Please note: if the transaction is approved, but the fields for Stored Credentials are not returned back in the API response, then the transaction is not processed as Stored Credentials. The reason: the API request with regards to Stored Credentials was not structured properly (e.g., typo in the field name) and hence these fields were dropped.

For Visa, Mastercard and Discover, the following API fields are applicable.

Field Name

Valid Values

stored_credentials

A nesting object. The API fields of Stored Credentials are nested under this object

indicator

For Visa and Discover:
"1" - First time transaction
"S" - Subsequent transaction

For Mastercard: merchants should send "S" in the Stored Credential Indicator. Merchants do not need to separately identify first and subsequent transactions.

initiation

"M" = Merchant Initiated
"C" = Cardholder Initiated

schedule

"U" = Unscheduled
"S" = Scheduled

authorization_type_override

Field is used for Visa only:

"R" = Reauthorization of Prior Amount
"A" = Resubmission
"E" = Estimated Authorization
Space = Default

transaction_id

Field is used for Visa and Discover only:

An identifier, assigned by Visa or Discover, to uniquely identify and link all related messages and records used to authorize and settle a transaction.

If Merchant requires the original transaction ID, set this record with the value equals “new” in the original authorization request. The “transaction_id” field will be returned in the API response provided the transaction is approved.

If an original transaction ID is created, it must be submitted in any follow-up transaction (ex. with recurring transactions).

original_amount

Field is used for Discover only:

Approved amount in the original authorization.

"original_amount" is returned via the API response and must be used in the subsequent transactions. Without it, subsequent transactions may reject with Bank Response Code 225 (Invalid Field Data).

protectbuy_indicator

Field is used for Discover only:

If the original authorization was ProtectBuy, submit “Y” in subsequent transactions.
Do not submit protectbuy_indicator with the original authorization.
If protectbuy_indicator field is used, submit this field together with transaction_id and original_amount

For American Express only, the following API fields are applicable. Above Visa, Mastercard, Discover fields are not submitted.

Field Name

Valid Values

ecommerce_flag

'2' for payments scheduled at regular frequency.

Supports recurring transaction applications such as: membership dues, subscriptions services, insurance premiums, wireless services, and other regularly scheduled charges. The billing amount can vary but the frequency is scheduled.

ecommerce_flag

'X' for Re-authorized Transactions.

Designates a non-recurring purchase using a card on file.

Supports use cases where the cardholder information is on file and billing frequency and amount are variable.

This value should also be used to denote an American Express Payment Token transaction where cryptogram data is unavailable.