Card-on-File

Mastercard, Visa, and Discover payment brands have implemented functionality to further secure recurring transactions. Depending on the card brand, this functionality is called:

  • Card-on-file (Mastercard)

  • Credential-on-file (Visa)

  • Stored Payment Tokens (Discover)

Auric documentation uses the generic card-on-file (CoF) terminology.

American Express does not implement card-on-file functionality. Payment gateways supporting card-on-file recommend you treat American Express cards the same way you do Mastercard, Visa, and Discover.

Terminology

  • Initial Transaction: Your first transaction (auth/sale) with a customer’s credit card.

  • Customer Initiated Transaction (CIT): Customer requests a transaction using the previously tokenized credit card number. For example, using the tokenized data to order new products from an e-commerce website.

  • Merchant Initiated Transaction (MIT): Merchant performs a payment transaction (auth/sale) using the previously tokenized credit card number. A monthly recurring billing, for example.

  • Externally Vaulted: Payment data stored outside the payment gateway. An AuricVault® token, for example.

Each gateway implements this functionality differently. The AuricVault® service provides a single consistent interface that maps to each payment processor’s specific requirements.

There are no API changes if you only intend to do one-time transactions.

Supported Gateways

The AuricVault® Payments Passthrough option supports card-on-file functionality for the following gateways:

  • Braintree

  • Chase Paymentech Orbital Gateway (pending)

  • Merchant e-Solutions (pending)

  • Worldpay (pending)

Gateways Without CoF

The following gateways do not yet support card-on-file functionality:

  • Tsys Transaction Express (TXP)

  • Windcave (formerly PaymentExpress)

Initial Transaction

The initial payment transaction must indicate the merchant’s intent to do subsequent transactions with the tokenized card. “Subsequent transactions” can be:

  • recurring (monthly billing for a service)

  • installment (three easy payments)

  • unscheduled (customer places another order)

../_images/cof-initial.svg

Request

The initial payment transaction uses one of the following commerceIndicator parameter values to indicate you intend to use this card for future transactions.

  • initialInstallment

  • initialRecurring

  • initialCardOnFile

  • initial3dsAttempted

  • initial3dsAuthenticated

Response

The initial payment transaction response may include a cardOnFileTransactionId value. If this value exists, you must store it for use with future transactions.

The cardOnFileTransactionId parameter is:

  • ASCII alphanumeric.

  • Maximum length of 80 characters.

Some processors return multiple fields which the AuricVault® service encodes into a single field. The processor-specific documentation describes if multiple fields are encoded and how they are encoded.

Note

There are various payment brand and gateway reasons a cardOnFileTransactionId is not returned. Your code must not assume it will always be returned.

Customer Initiated

When a customer triggers a payment transaction, you must indicate the customer initiated the transaction and is using a previously tokenized card number.

../_images/customer-initiated-transaction.svg

Request

  • Set cardOnFileTransactionId to the value from the initial transaction.

  • Set merchantInitiated to ‘false’.

  • Set commerceIndicator to ‘recurring’ or ‘installment’; or ‘cardOnFile’ (if transaction is neither an installment nor recurring).

Response

No changes to the expected response data.

Merchant Initiated

When you process an installment or repeat billing payment transaction, you must indicate you initiated a transaction and are using a previously tokenized card number.

../_images/merchant-initiated-transaction.svg

Request

  • Set cardOnFileTransactionId to the value from the initial transaction.

  • Set merchantInitiated to ‘true’.

  • Set commerceIndicator to ‘recurring’ or ‘installment’; or

  • Set commerceIndicator to ‘cardOnFile’ if transaction is neither an installment nor recurring.

Response

No changes to the expected response data.

Note

Some processors return a new cardOnFileTransactionId for each subsequent auth/sale transaction. If your processor returns a new value you should store it and use the new value for your next card-on-file transaction. Refer to your payment gateway representative for details.