---
url: >-
  https://acquirer-api-docs-v4-en.pingpongx.com/notes/zh/integrate/tokenization/cardOnFile/index.md
description: 说明国际信用卡首次支付并保存卡的接入方式，覆盖 Hosted、Non-Hosted 和 CardOnFile 首笔差异。
---
## 适用场景

本文适用于以下场景：

- 首次支付时希望同时保存卡信息，便于后续复购
- 需要通过收银台或服务端完成首笔支付并生成后续可复用凭证
- 需要在首笔接入时区分普通保存卡交易与 `CardOnFile` 交易模式

## 首笔保存卡可按两种方式处理

无论选择哪种方式，首笔交易都可以完成支付并保存卡信息。

区别不在于能否保存卡，而在于后续交易按哪种已存卡方式处理。

| 方式 | 首笔是否保存卡 | 后续支付分类 | 在 PingPong 中的典型表现 | 典型场景 |
|:-----|:---------------|:-------------|:-------------------------|:---------|
| 普通保存卡交易 | 是 | 普通已保存卡复购 | 通常仍需补充 CVV 等安全信息 | 记住卡号、提升复购体验、安全校验要求较高的场景 |
| CardOnFile 交易模式 | 是 | `CIT CoF` | 通常可免 CVV，直接完成一键支付 | 持卡人在场的一键支付（One-click checkout） |

如果只是希望保存卡信息、提升用户后续支付体验，默认建议使用普通保存卡交易。
只有当你希望持卡人后续支付时无需重新输入 CVV、直接一键完成支付，再使用 `CardOnFile` 交易模式。

## 如何选择

**优先选普通保存卡交易，如果：**
- 每次支付都需要额外安全校验（如输入 CVV）
- 你准备自己保存 PAN/有效期，不依赖 PSP token
- 只是希望用户减少输入完整卡号，但仍需每次验证

**优先选 CardOnFile 交易模式，如果：**
- 复购频次高，寻求提升支付转化率
- 希望持卡人选择已保存卡后直接完成支付
- 已完成持卡人保存卡和后续使用授权的告知，并评估免 CVV 场景的业务风险

### 普通保存卡交易

适用于仅希望保存卡信息、提升用户支付体验的场景。

后续支付时，用户可基于已保存卡信息完成复购；根据接入方式不同，通常需要补充必要的安全信息，或由商户按普通交易方式继续发起支付。

### CardOnFile 交易模式

`CardOnFile` 首先是一种已存卡交易模式，用于标识持卡人在场的 `CIT CoF` 场景。

在 PingPong 中，首笔绑卡并支付及后续复购需统一按照 `CardOnFile` 交易模式处理，后续通常可免 CVV 完成一键支付。

## 持卡人授权与告知

在首笔保存卡前，建议商户在自有产品流程中明确完成以下事项：

- 告知持卡人本次将保存卡信息，用于后续已存卡支付
- 告知后续支付的使用范围，例如仅用于持卡人在场的一键支付，或另行授权的 MIT 代扣
- 在商户侧留存持卡人同意保存卡和后续使用的记录

如果后续还需要持卡人不在场的代扣能力，请按 `Recurring` 文档要求单独处理授权关系，不要将 `CardOnFile` 与 MIT 代扣混用。

## Hosted 接入

Hosted 模式下，首笔支付并保存卡的基本方式如下：

1. 调用[收银台预下单](/notes/zh/checkout/api/reserve/)创建支付会话
2. 传入 `merchantUserId`，用于标识当前持卡人身份并关联其已保存卡信息
3. 如果首笔交易需要按 `CardOnFile` 交易模式处理，再额外传入 `bizType=CardOnFile`
4. 用户在收银台完成支付，并勾选保存卡选项
5. 系统保存卡信息，后续支付时可展示已保存卡列表

::: note 说明
Hosted 模式下，保存卡动作由收银台交互承接，用户在收银台勾选保存卡选项后即可完成保存卡。
:::

## Non-Hosted 接入

Non-Hosted 模式下，首笔支付并保存卡的基本方式如下：

1. 商户自行发起下单并支付请求
2. 传入 `merchantUserId`，用于标识当前持卡人身份并关联其已保存卡信息
3. 传入 `createToken=Y`，表示本次支付成功后创建可复用凭证
4. 如果首笔交易需要按 `CardOnFile` 交易模式处理，再额外传入 `bizType=CardOnFile`
5. 支付完成后，通过异步通知或主动查询获取 `token`

## 首笔关键参数

| 参数字段 | 是否必需 | 说明 |
|:---------|:---------|:-----|
| `merchantUserId` | 是 | 商户网站的持卡人 ID，用于标识当前持卡人身份并关联其已保存卡信息 |
| `createToken` | 仅 Non-Hosted 保存卡场景必需 | 用于控制本次支付成功后是否生成可复用的支付凭证。Non-Hosted 首笔保存卡并需生成支付凭证时传 `Y` |
| `bizType` | 可选 | Hosted 或 Non-Hosted 首笔如需按 `CardOnFile` 交易模式处理时传 `CardOnFile` |
| `token` | 首笔成功后返回 | 保存卡成功后返回的支付凭证，可用于后续基于 token 的支付场景 |

## 首笔接入规则

### 普通保存卡交易

以下仅展示请求中与保存卡相关的关键字段。

**Hosted（prePay）**

```json title="bizContent 关键字段"
{
  "merchantUserId": "USER_12345"
}
```

**Non-Hosted（unifiedPay）**

```json title="bizContent 关键字段"
{
  "merchantUserId": "USER_12345",
  "createToken": "Y"
}
```

无需传 `bizType=CardOnFile`。

### CardOnFile 交易模式

以下仅展示请求中与保存卡相关的关键字段。

**Hosted（prePay）**

```json title="bizContent 关键字段"
{
  "merchantUserId": "USER_12345",
  "bizType": "CardOnFile"
}
```

**Non-Hosted（unifiedPay）**

```json title="bizContent 关键字段"
{
  "merchantUserId": "USER_12345",
  "createToken": "Y",
  "bizType": "CardOnFile"
}
```

::: note PingPong 平台规则
若首笔生成 token 时传了 `bizType=CardOnFile`，后续使用该 token 复购时也需继续传 `bizType=CardOnFile`。

若首笔未按 `CardOnFile` 交易模式创建该 token，则后续不应将该 token 直接切换为 `CardOnFile` 路径使用。
:::

### 仅校验卡信息

如果只是校验卡号或卡要素，不属于“首次支付并保存卡”场景，无需传 `bizType=CardOnFile`。

## 后续接入

首笔支付并保存卡完成后，商户可根据后续支付方式选择不同接入路径：

- [收银台复购（已保存卡 + CVV）](/notes/zh/integrate/tokenization/cardOnFileCVV/)：通过收银台展示已保存卡并收集 CVV
- [服务端复购（Token 支付 / 一键支付）](/notes/zh/integrate/tokenization/cardOnFileNonHosted/)：商户服务端使用 token 发起后续支付，若首笔传了 `bizType=CardOnFile` 则无需 CVV

::: warning 注意
后续无需输入 CVV，并不代表交易一定不会被要求额外认证。实际授权结果仍取决于发卡行风控、监管要求以及交易风险。
:::