> ## Documentation Index
> Fetch the complete documentation index at: https://docs.localpayment.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 测试

完整的集成测试指南。测试数据、测试场景和验证清单。

上线前务必对 Localpayment 集成进行全面测试。本指南提供了测试数据、测试场景和验证流程，确保您的集成在所有支付方式和特殊情况下都能正常运行。

## 先决条件

开始测试前，请确保已完成以下配置：

> [card] [API凭证](https://docs.localpayment.com/zh/docs/api-keys-and-environments.md)
>
> 用于身份验证的有效 API 凭据和访问令牌。

> [card] [账户设置](https://docs.localpayment.com/zh/docs/make-your-first-test-payment.md)
>
> 为您的目标国家/地区正确设置账户并进行业务验证。

> [card] [IP白名单](https://docs.localpayment.com/zh/docs/dashboard-whitelist-your-ips.md)
>
> 将服务器 IP 地址加入 API 访问白名单。

> [card] [Webhook endpoint](https://docs.localpayment.com/zh/docs/webhooks.md)
>
> 设置 webhook URL 以接收付款通知。

***

## 沙盒环境

Stage 环境是我们生产系统的完整副本，专为测试而设计：

> [card] 真实处理
>
> 模拟实际支付流程和时间。

> [card] 没有真钱
>
> 所有交易均使用测试数据。

> [card] 完整功能集
>
> 所有支付方式和操作均可用。

> [card] 独立测试
>
> 您的测试版数据与生产版数据是分开保存的。

***

## 测试数据

### 银行卡支付

测试各种场景下的信用卡和借记卡支付：

| 卡号 | 场景 | 预期结果 | 测试目的 |
| - | - | - | - |
| 4242424242424242 | ✅ 付款成功 | 立即批准 | 基本支付流程 |
| 4000000000000002 | ❌ 卡片被拒 | 有理由地拒绝 | 拒绝处理 |
| 4000002500003155 | 🔐 需要 3D 安全验证 | 身份验证重定向 | 3D 安全流程 |
| 4000000000009995 | ⚠️ 处理错误 | 暂时性故障 | 余额核对 |

**标准卡片详情：**

* **到期日**：任何未来的日期（例如，2029年12月）
* **CVC**：万事达卡和维萨卡的任意 3 位数字（例如 123），或美国运通卡的任意 4 位数字（例如 1234）。
* **持卡人姓名**：任意测试名称（例如，“John Doe”）

***

## 错误场景测试

### 验证错误

* 省略必填字段（paymentMethod、amount）
* 使用无效格式（货币错误、文件编号无效）
* 测试参数限制（数量限制、国家/地区限制）

### 身份验证测试

* 使用过期的访问令牌
* 使用无效凭据进行测试
* 验证 IP 白名单限制

***

## Webhook 测试

请确保您的 webhook endpoint 能够正确处理通知：

### endpoint 配置

* 验证 HTTPS 要求
* 测试签名验证
* 确认立即返回 200 OK 响应

### 事件处理

* 测试所有事件类型（充值、支付、虚拟账户）
* 验证幂等处理
* 确认异步处理

### 错误处理

* 测试超时场景
* 验证重试逻辑
* 监控投递失败情况

***

## 虚拟账户模拟（Stage）

对于虚拟账户集成，Localpayment 提供了一个专用的模拟 endpoint 来测试完整的生命周期（创建 -> 资金 -> 通知）。

### 虚拟账户支付（模拟）

要在 Stage 中模拟成功付款，请使用创建虚拟账户时提供的相同受益人数据——姓名、单据类型和单据 ID。无需单独的测试身份；[模拟虚拟账户付款](https://docs.localpayment.com/zh/reference/simulate-payin-to-virtual-account.md)endpoint 会将付款人数据与账户创建期间注册的信息进行比对验证。

### 核心测试场景：

| 场景 | 目标 | 要求 |
| :- | :- | :- |
| **验证状态** | 确认账户激活 | 创建虚拟账户后，请检查[获取虚拟账户状态](https://docs.localpayment.com/zh/reference/get-virtual-account-status.md)。 |
| **模拟收款** | 触发模拟付款 | 使用与创建账户时相同的受益人数据，[模拟虚拟账户付款](https://docs.localpayment.com/zh/reference/simulate-payin-to-virtual-account.md)。 |
| **Webhook 交付** | 验证监听器逻辑 | 请确保模拟完成后收到 `payin.completed`（status：`COMPLETED`）。 |

> [!NOTE]
>
> **重要**
>
> * **字段映射**：在模拟调用中，请使用[获取虚拟账户状态](https://docs.localpayment.com/zh/reference/get-virtual-account-status.md) 返回的 `beneficiary.bank.account.number` 来标识目标账户。模拟请求中的 `externalId` 应为该 payin 交易的唯一标识符——每次请求请使用不同的值。同时请包含您真实的 **accountNumber**（商户 ID）以标识项目。
> * **身份信息**：使用创建虚拟账户时提供的相同受益人数据，包括姓名、证件类型和身份证件。详情请参阅[完整模拟指南](https://docs.localpayment.com/zh/docs/simulate-virtual-account-payment.md)。

***

## 验证清单

在投入生产环境之前，请验证以下内容：

* **支付流程**：确认所有支付方式均能正常运行，包括成功和失败两种情况。
* **Webhook 处理**：确保所有 webhook 事件均按预期接收、验证和处理。
* **错误处理**：向用户显示清晰的错误信息，并在需要时实施适当的重试逻辑。
* **安全**：强制使用 HTTPS，验证签名，并确保所有敏感数据得到安全处理。
* **用户体验**：在整个支付过程中提供清晰的加载状态、有用的消息提示和流畅的重定向流程。

***

## 测试工具

下载我们完整的 Postman 集合，其中包含预配置的测试场景：

> [card] [Postman 集合](https://docs.localpayment.com/zh/reference/postman-collection.md)
>
> 获取包含环境模板的完整测试集


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.