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 classified and processed.

Method	Is the card saved in the first payment	Classification for subsequent payments	Typical behavior in PingPong	Typical scenarios
Regular saved-card transaction	Yes	Regular saved-card repeat purchase	Usually still requires CVV or other security information	Remember card details, improve repeat purchase experience, scenarios requiring higher security verification
CardOnFile transaction	Yes	CIT CoF	Typically CVV-free one-click checkout	Cardholder-present one-click checkout

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 want the shopper to complete subsequent payments by selecting a saved card without re-entering CVV.

How to choose

Choose a regular saved-card transaction if:

• Each payment needs an extra security check (such as CVV)
• You plan to store PAN/expiry dates yourself instead of relying on PSP tokens
• You want to reduce repeated card number entry but still require verification each time

Choose a CardOnFile transaction if:

• You have high repeat-purchase frequency and want to improve payment conversion
• You want the cardholder to select a saved card and complete payment immediately
• You have completed cardholder notice and consent for card storage and subsequent use, and have assessed the business risk of a CVV-free scenario

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

CardOnFile is first a stored credential transaction model used to identify a cardholder-initiated CIT CoF scenario.

In PingPong, both the initial bind-and-pay transaction and subsequent repeat purchases must consistently follow the CardOnFile transaction path. Subsequent payments can typically be completed without re-entering CVV.

Cardholder Notice and Consent

Before the first saved-card payment, the merchant should clearly complete the following steps in its own product flow:

• Inform the cardholder that the card details will be saved for subsequent stored-card payments
• Explain the scope of later use, such as one-click payments when the cardholder is present or a separately authorized MIT charge flow
• Keep a record of the cardholder's consent to card storage and later use

If you also need merchant-initiated charges when the cardholder is not present, follow the Recurring documentation separately. Do not mix CardOnFile with MIT charging logic.

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"
}

PingPong platform rule

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

If the token was not created under the CardOnFile path, do not later switch that token into the CardOnFile path for subsequent payments.

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 / One-click) - Use token from the merchant server for subsequent payments; no CVV required if bizType=CardOnFile was passed on the first payment

Note

No CVV input for subsequent payments does not mean extra authentication will never be required. Authorization outcomes still depend on issuer risk controls, regulatory requirements, and transaction risk.

Previous pageOverview and Integration Choice

Next pageCheckout Repeat Purchase (Stored Card + CVV)