Card-on-File payments

Card-on-File (COF) lets you save the customer's card during a payment and charge it later without asking for the card data again. You save the card once and then pay with its card_token.

A later payment is either a customer-initiated transaction (CIT), where the customer takes part and confirms the payment, or a merchant-initiated transaction (MIT), where you charge the card without the customer.

Card-on-File works in S2S CARD and Checkout.

Before you start

• Enabled for your MID. Your account manager enables Card-on-File for your MID (merchant ID). Your acquirer must also support it. Payment Platform then registers saved cards with the acquirer as stored credentials.
• Acquirer limits. Some acquirers do not accept Card-on-File for an authorization (auth=Y) or together with recurring_init, and decline such a payment. Ask your account manager which operations your acquirer supports.
• Without Card-on-File. You can still save cards and pay with card_token. Payment Platform keeps the card and sends the full card data to the acquirer with each payment.

Save the card

The first payment is a CIT with the full card data.

1. Send the payment with the card data and req_token:
   • S2S CARD: SALE (including auth=Y) or DEBIT, with req_token=Y.
   • Checkout: the Authentication request with req_token: true.
2. If the payment needs 3-D Secure (3DS), you get REDIRECT in S2S CARD. See Redirect / 3DS handling.
3. When the payment succeeds, get the card_token from the callback or the status response. In S2S CARD, the SALE response also returns it.
4. Store the card_token with your customer's record.

A card you saved before Card-on-File was enabled is registered with the acquirer the first time you pay with its card_token.

Pay with a saved card

S2S CARD

Send card_token in SALE or DEBIT instead of the card number and expiry date. card_cvv2 is optional with card_token.

Use payer_present to tell Payment Platform who starts the payment:

payer_present	Payment	Example
Y (default)	CIT: the customer is in your app or on your website and confirms the payment.	One-click checkout with a saved card.
N	MIT: you charge the card without the customer.	A charge for extra services after the customer leaves, an automatic account top-up.

payer_present takes effect only on payments with card_token. A payment with card data is always a CIT. A CIT with card_token can also get REDIRECT.

Checkout

Send the customer's saved tokens in the card_token array of the Authentication request. The payment page shows these cards masked, and the customer selects one. In Checkout the customer is always present, so these payments are CITs. Whether the customer must enter the card verification code (CVV) for a saved card depends on your account settings. Ask your account manager.

Recurring payments

Recurring payments use their own token, recurring_token, and their own requests:

1. Start the chain with recurring_init=Y in S2S CARD, or recurring_init: true in a Checkout purchase. This first payment is a CIT.
2. Charge the next payments with RECURRING_SALE or RECURRING_DEBIT in S2S CARD, with the Checkout Recurring Sale request, or from a recurring schedule. These payments are MITs.

See Recurring payments in S2S CARD and Recurring payments in Checkout.

Payment attributes

Payment Platform marks each card payment with three attributes. They are not sent by default: ask your account manager to enable them in Protocol Mapping for the callback, the status response, or both. You then get them in:

• the callback,
• the S2S CARD GET_TRANS_STATUS, GET_TRANS_DETAILS, and status by order ID responses,
• the Checkout status response.

Attribute	Values
initiator	customer: the customer started the payment. merchant: you started the payment without the customer.
sequence	one_off: a single payment without a saved card. initial: the payment that saved the card or started a recurring chain. subsequent: a later payment with a saved card, or a later recurring payment.
source	card: card data sent in the request. card_on_file: saved card registered with the acquirer as a stored credential. network: saved card sent with a network token. internal: saved card whose data only Payment Platform keeps. recurring: recurring payment.

Typical combinations:

Payment	initiator	sequence	source
Card data, no req_token	customer	one_off	card
Card data with req_token, card saved for the first time	customer	initial	card
First payment with recurring_init	customer	initial	card
card_token with payer_present=Y	customer	subsequent	card_on_file, network, or internal
card_token with payer_present=N	merchant	subsequent	card_on_file, network, or internal
RECURRING_SALE, RECURRING_DEBIT, or a payment from a recurring schedule	merchant	subsequent	recurring

What's next

• Network tokens
• MOTO payments
• Card data tokenization in Checkout
• SALE parameters in S2S CARD