---
url: >-
  https://acquirer-api-docs-v4-en.pingpongx.com/en/notes/onlinePayment/features/tokenization/cardOnFileCVV/index.md
description: >-
  This page explains how to display stored card information through the embedded
  checkout and collect CVV for repeat purchases. Checkout displays stored cards
  based on merchantUserId. If one shopper has multiple stored cards and you only
  want to show one of them, use the prePay cardToken parameter together with SDK
  customizeConfig.
---
## Use Cases

- The shopper already has a stored card on the merchant platform and only needs to enter CVV for a repeat purchase
- Sub-account or delegate scenarios where the user is not the original cardholder and CVV collection is needed for additional security verification

## Prerequisites

- Completed the [First Payment and Save Card](/en/notes/onlinePayment/features/tokenization/cardOnFile/) flow
- Enabled [Embedded SDK (Pre-order)](/en/notes/integrate/sdk-v4/) integration
- If the same `merchantUserId` has multiple stored cards and you want to show only one of them in the current payment, obtain the target card token from a stored-card record or the [Bind List API](/en/notes/tokenization/cof/bindList/)

## Overall Information Flow

```mermaid
sequenceDiagram
    actor User as 👤 User
    participant Frontend as 💻 Merchant Frontend
    participant Backend as 🏪 Merchant Backend
    participant PP as 🔄 PingPongCheckout

    Note over User, PP: 🚀 First Payment: Pay and Save Card

    Frontend->>+Backend: 1. Submit first order (merchantUserId, and bizType=CardOnFile if this flow should be processed as CardOnFile)
    Backend->>+PP: 2. Request payment API
    PP-->>-Backend: 3. Return payment result and save card information
    Backend-->>-Frontend: 4. Return payment result

    Note over User, PP: 🔄 Repeat Purchase: CVV Collection Checkout

    User->>Frontend: 5. Start repeat purchase
    Frontend->>+Backend: 6. Submit repeat order (merchantUserId; optionally add cardToken if you want to show only one specific card)
    Backend->>+PP: 7. Call prePay API (retrieve stored cards based on merchantUserId; if cardToken is passed, only the corresponding card is shown)
    PP-->>-Backend: 8. Return accessToken
    Backend-->>-Frontend: 9. Return accessToken
    Frontend->>Frontend: 10. Render checkout (stored card information + CVV input only)
    User->>Frontend: 11. Enter CVV and confirm payment
    Frontend->>+PP: 12. Submit payment (including CVV)
    PP-->>-Frontend: 13. Return payment result
    PP->>Backend: 14. 📡 Async notification with final result
    Backend-->>PP: 15. 🟢 HTTP 200
```

## Integration Steps

### 1. Backend: Call the prePay API

When calling the [prePay API](/en/notes/checkout/api/reserve/), add the following field in `bizContent`:

| Parameter | Type | Required | Description |
|:----------|:-----|:---------|:------------|
| `cardToken` | String | No | Optional field. Checkout displays stored cards based on `merchantUserId`. Pass this field only when the same shopper has multiple stored cards and you want to show just one of them in the current payment. If the shopper has only one stored card, do not pass this field |

```json title="prePay Request Example (CVV Collection Scenario)"
{
  "accId": "2018092714313010016291",
  "clientId": "2018092714313010016",
  "signType": "SHA256",
  "version": "1.0",
  "bizContent": {
    "cardToken": "<optional in multi-card scenarios: target stored-card token>",
    "merchantTransactionId": "ORDER_COF_001",
    "amount": "100",
    "currency": "USD",
    "merchantUserId": "user_12345"
  }
}
```

### 2. Frontend: Configure the checkout SDK

::: note cardToken source
In CVV collection scenarios, whether stored cards are displayed in checkout is determined first by `merchantUserId`. `cardToken` is only used in multi-card scenarios to limit the display to one specific card. If the shopper has only one stored card, do not pass it. The value passed in this field is the stored-card record token, which can be obtained through the [Bind List API](/en/notes/tokenization/cof/bindList/).
:::

When initializing the [Embedded SDK](/en/notes/integrate/sdk-v4/), use `customizeConfig` to control the checkout behavior:

```js title="Recommended Configuration for CVV Collection"
PingPong.Checkout.customizeConfig = {
    hideStoredCards: false,        // Show the stored card list
    onlyDisplaySavedCard: true,    // Only display stored cards (hide new card input)
    disableCardRemoval: true       // Prevent stored cards from being removed
};
```

::: note Configuration effects
- Only stored card information is displayed; new card input is hidden
- Card information (brand, masked card number, expiry date) is read-only
- Stored cards cannot be removed
- Checkout shows only the CVV input field for the shopper to fill in
:::

::: warning Note
`customizeConfig` must be configured after the SDK has loaded and before setting `accessToken`.
:::

### 3. Frontend: Complete integration example

```html title="Complete CVV Collection Checkout Example"
<!DOCTYPE html>
<html>
<head>
    <!-- Import SDK (sandbox URL shown here; replace with the production URL when going live) -->
    <script type="module" src="https://payssr-cdn.pingpongx.com/production-fra/acquirer-checkout-web/sandbox/pp-checkout.js"></script>
</head>
<body>
    <pp-checkout id="ppCheckout" locale="en"></pp-checkout>

    <script>
        // 1. Configure checkout for CVV collection mode
        PingPong.Checkout.customizeConfig = {
            hideStoredCards: false,
            onlyDisplaySavedCard: true,
            disableCardRemoval: true
        };

        // 2. Optional payment failure callback
        PingPong.Checkout.checkoutFailedHook = (code, message) => {
            console.error(`Payment failed [${code}]: ${message}`);
        };

        // 3. Set accessToken after receiving it from the backend
        const ppCheckout = document.getElementById('ppCheckout');
        ppCheckout.setAttribute('accessToken', '<accessToken_from_prePay_API>');
    </script>
</body>
</html>
```

## Checkout Display Rules

When `cardToken` is passed in a CVV collection scenario:

| Area | Display rule |
|:-----|:-------------|
| Card Number | Displays only the masked number (for example `**** **** **** 1234`), read-only |
| Expiry Date | Displayed separately, read-only |
| Selection Button | Hidden; no radio button for choosing another stored card |
| CVV Input | Displayed; this is the only editable payment field |

## Related Documentation

- [First Payment and Save Card](/en/notes/onlinePayment/features/tokenization/cardOnFile/) - Save card information during the first payment and obtain a reusable payment credential
- [Embedded SDK (Pre-order)](/en/notes/integrate/sdk-v4/) - SDK initialization and configuration details
- [prePay API](/en/notes/checkout/api/reserve/) - Server-side order API