---
url: >-
  https://acquirer-api-docs-v4-en.pingpongx.com/en/notes/onlinePayment/features/tokenization/cardOnFile/index.md
description: >-
  This page explains how to save card information during the first international
  card payment, covering both Hosted and Non-Hosted integration modes. It also
  clarifies the difference between a regular saved-card transaction and a
  CardOnFile transaction during the first payment.
---
## 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](/en/notes/checkout/api/reserve/) 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 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)**

```json title="Key fields in bizContent"
{
  "merchantUserId": "USER_12345"
}
```

**Non-Hosted (unifiedPay)**

```json title="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)**

```json title="Key fields in bizContent"
{
  "merchantUserId": "USER_12345",
  "bizType": "CardOnFile"
}
```

**Non-Hosted (unifiedPay)**

```json title="Key fields in bizContent"
{
  "merchantUserId": "USER_12345",
  "createToken": "Y",
  "bizType": "CardOnFile"
}
```

::: note 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)](/en/notes/onlinePayment/features/tokenization/cardOnFileCVV/) - Display stored cards in checkout and collect CVV
- [Server-side Repeat Purchase (Token Payment / One-click)](/en/notes/onlinePayment/features/tokenization/cardOnFileNonHosted/) - Use token from the merchant server for subsequent payments; no CVV required if `bizType=CardOnFile` was passed on the first payment

::: warning 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.
:::