Use Cases

This page is intended for the following scenarios:

• You want to save card information during the first payment for future purchases
• You need to complete the first payment through checkout or server-side API and generate a reusable payment credential
• You need to distinguish between a regular saved-card transaction and a CardOnFile transaction during the first payment

The first saved-card payment can be handled in two ways

Whichever method you choose, the first payment can both complete the payment and save the card information.

The difference is not whether the card can be saved, but how subsequent transactions are processed.

Method	Is the card saved in the first payment	How subsequent transactions are processed	Typical scenarios
Regular saved-card transaction	Yes	Subsequent transactions are still processed as regular transactions	Remember card details, improve repeat purchase experience
CardOnFile transaction	Yes	Subsequent transactions are processed as stored credential transactions	One-click Payment, Subscription, Merchant Initiated Transaction (MIT), direct payment with a stored card

If you only want to save card information and improve the shopper's repeat purchase experience, we recommend using a regular saved-card transaction by default.
Use a CardOnFile transaction only when you explicitly need subsequent payments to be processed as stored credential transactions.

Regular saved-card transaction

This is suitable when you only want to save card information and improve the payment experience.

For subsequent payments, the shopper can pay using the stored card information. Depending on your integration method, the shopper usually needs to provide required security information such as CVV, or the merchant continues to process the transaction as a regular payment.

CardOnFile transaction

This is suitable when you want to initiate subsequent transactions based on stored card information and have them processed as stored credential transactions, for example:

• One-click Payment
• Subscription
• Merchant Initiated Transaction (MIT)
• Direct payment after the shopper selects a stored card

In these scenarios, both the initial bind-and-pay transaction and subsequent repeat purchases should consistently follow the CardOnFile transaction rules.

Hosted Integration

In Hosted mode, the basic first-payment flow is:

1. Call the Checkout prePay API to create a payment session
2. Pass merchantUserId to identify the current cardholder and associate their stored card information
3. If the first transaction needs to be processed as a CardOnFile transaction, also pass bizType=CardOnFile
4. The shopper completes the payment in checkout and selects the save-card option
5. The system stores the card information so it can be displayed in later payments

Note

In Hosted mode, the save-card action is handled by the checkout interaction. The shopper saves the card by selecting the save-card option in checkout.

Non-Hosted Integration

In Non-Hosted mode, the basic first-payment flow is:

1. The merchant initiates the order-and-pay request directly
2. Pass merchantUserId to identify the current cardholder and associate their stored card information
3. Pass createToken=Y so a reusable payment credential is created after the payment succeeds
4. If the first transaction needs to be processed as a CardOnFile transaction, also pass bizType=CardOnFile
5. After payment completion, obtain the token through async notification or active query

Key Parameters for the First Payment

Parameter	Required	Description
merchantUserId	Yes	The merchant-side cardholder ID used to identify the current cardholder and associate their stored card information
createToken	Required only in Non-Hosted saved-card scenarios	It controls whether a reusable payment credential is generated after the current payment succeeds. In Non-Hosted mode, pass Y when the first saved-card payment needs to generate a payment credential
bizType	Optional	Pass CardOnFile when the first Hosted or Non-Hosted payment should be processed as a CardOnFile transaction
token	Returned after the first payment succeeds	The payment credential token returned after saving the card, which can be used for subsequent token-based payments

First-payment Rules

Regular saved-card transaction

Only the key fields related to saved-card behavior are shown below.

Hosted (prePay)

Key fields in bizContent

{
  "merchantUserId": "USER_12345"
}

Non-Hosted (unifiedPay)

Key fields in bizContent

{
  "merchantUserId": "USER_12345",
  "createToken": "Y"
}

Do not pass bizType=CardOnFile.

CardOnFile transaction

Only the key fields related to saved-card behavior are shown below.

Hosted (prePay)

Key fields in bizContent

{
  "merchantUserId": "USER_12345",
  "bizType": "CardOnFile"
}

Non-Hosted (unifiedPay)

Key fields in bizContent

{
  "merchantUserId": "USER_12345",
  "createToken": "Y",
  "bizType": "CardOnFile"
}

If bizType=CardOnFile was passed when the token was first created, subsequent transactions using that token must continue to pass bizType=CardOnFile.

Card Verification Only

If you are only verifying card validity or card details, this is not a "first payment and save card" scenario, so you do not need to pass bizType=CardOnFile.

Next Integration Steps

After the first payment and saved-card setup is completed, choose the next path based on how subsequent payments will be made:

• Checkout Repeat Purchase (Stored Card + CVV) - Display stored cards in checkout and collect CVV
• Server-side Repeat Purchase (Token Payment) - Use the token from the merchant server for subsequent payments
• CardOnFile Transaction Rules - See when to pass bizType=CardOnFile and how the first payment rules carry into later token-based payments

Previous pageOverview and Integration Choice

Next pageCheckout Repeat Purchase (Stored Card + CVV)