> ## 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.

# 支付沙箱测试

在正式上线银行转账付款之前，使用 Stage 测试账户触发特定的付款拒绝场景。

在 Production 环境中向真实收款人付款之前，请先使用 Stage 环境确认您的集成既能处理付款成功的情况，也能处理收款人银行在实际中返回的各类拒绝场景。本指南介绍银行转账付款的沙箱流程，并提供按国家划分的专用测试账户，每个账户都会确定性地触发对应的拒绝场景。

## 开始之前

* 有效的 [API 凭证](https://docs.localpayment.com/zh/docs/api-keys-and-environments.md)（访问令牌），用于 Stage 环境。
* 熟悉[通过银行转账汇款](https://docs.localpayment.com/zh/docs/send-funds-via-bank-transfer.md)以及[创建付款](https://docs.localpayment.com/zh/reference/create-a-payout.md)的请求结构。
* 已配置 Webhook endpoint，用于接收付款状态通知。

***

## 沙箱如何模拟拒绝

Stage 不会转移真实资金，但其流程与 Production 相同：Localpayment 收到您的请求后会验证请求结构，如果格式正确，则将其设为 `In Progress`，并根据您提交的账户详情路由至模拟的银行响应。该响应决定批准还是拒绝该付款。您可以通过常规方式获知结果：通过 Webhook，或查询交易状态。

任何请求结构正确的付款都会被自动批准。本指南中的测试账户是例外：每个账户都映射到特定的拒绝原因，因此您可以按需重现该错误情形，而无需等待其自然发生。

```mermaid theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
%%{init: {'theme': 'base', 'themeVariables': {'primaryColor': '#31467c', 'primaryTextColor': '#ffffff', 'primaryBorderColor': '#0c1a29', 'actorBkg': '#31467c', 'actorBorder': '#0c1a29', 'actorTextColor': '#ffffff', 'actorLineColor': '#0c1a29', 'signalColor': '#0c1a29', 'signalTextColor': '#0c1a29', 'labelBoxBkgColor': '#31467c', 'labelBoxBorderColor': '#0c1a29', 'labelTextColor': '#ffffff', 'loopTextColor': '#0c1a29', 'noteBkgColor': '#ffffff', 'noteBorderColor': '#31467c', 'noteTextColor': '#0c1a29'}}}%%
sequenceDiagram
  autonumber
  participant Dev as 您的后端
  participant LP as Localpayment（Stage）
  participant Bank as 模拟银行响应

  Dev->>LP: POST /api/payout/ （测试用 beneficiary.bank 详情）
  LP->>LP: 校验请求字段
  LP-->>Dev: 响应：状态为 In Progress
  LP->>Bank: 路由该 payout
  Bank-->>LP: 批准，或使用对应的测试代码拒绝
  alt 已拒绝
    LP-->>Dev: Webhook：状态 REJECTED（code / description）
  else 已批准
    LP-->>Dev: Webhook：状态 COMPLETED
  end
  Dev->>LP: （或）GET payout 状态
  LP-->>Dev: 当前状态
```

1. 您使用下表中的某个测试账户在 Stage 中提交付款。
2. Localpayment 验证请求结构，如果有效，则在路由至模拟的银行响应期间将付款设为 `In Progress`。
3. 模拟的银行响应会评估收款人账户详情。结构正确但与下列测试账户均不匹配的账户会被自动批准。测试账户则会以其映射的代码被拒绝。
4. Localpayment 通过您的 Webhook endpoint 通知您最终状态，您也可以通过查询交易来获取。借此可确认您的集成能对 `REJECTED` 付款作出正确响应，而无需等待真实的银行拒绝。

> [!NOTE]
>
> 这些测试账户仅适用于 Stage。在 Production 中向这些账户付款不会产生相同的结果，因为 Production 会路由至真实银行。

***

## 拒绝代码

下面的每个测试账户都会返回以下五种结果之一。它们均会产生状态为 `REJECTED` 的付款，并带有相应的 `status.code` 和 `status.description`。

| 代码 | 说明 | 场景 |
| - | - | - |
| `701` | `InvalidAccountNumber` | 账号未通过格式或校验位验证。 |
| `702` | InvalidAccountNumber - Account Closed | 账号格式有效，但账户已关闭或处于非活动状态。 |
| `703` | InvalidAccountNumber - Account Blocked | 账号格式有效，但账户已被冻结。 |
| `640` | Transaction rejected by AML | 交易被反洗钱（AML）控制措施拒绝。 |
| `833` | Error account does not accept transfers | 目标账户或机构不接受转入的转账。 |

***

## 各国测试账户

每个标签页列出一个国家的收款银行详情。每个场景共用相同的 `paymentMethod.code`，并且除非另有说明，该国家的 `beneficiary.bank.code` 和 `beneficiary.bank.name` 也相同。`account.details` 是要在 `beneficiary.bank.account.number`（或在特别注明时为 `beneficiary.bank.account.alias`）中发送的值，用于触发对应的拒绝代码。`Description`是您在该代码的响应和 Webhook 中看到的 `status.description`。

> [tab] 阿根廷
>
> **付款方式：** COELSA，代码 `0010` · **银行：** BANCO DE GALICIA (`007`) · `account.type`: `S` · `account.details` 为 CBU
>
> | 代码 | `account.details` | 说明 |
> | - | - | - |
> | `701` | `0070001600000000000017` | `InvalidAccountNumber` |
> | `702` | `0070001600000000000024` | InvalidAccountNumber - Account Closed |
> | `703` | `0070001600000000000031` | InvalidAccountNumber - Account Blocked |
> | `640` | `0070001600000000000048` | Transaction rejected by AML |
> | `833` | `0070001600000000000055` | Error account does not accept transfers |
>
> `account.type` 为 `C`（支票账户）时同样适用于这些场景。

> [tab] 玻利维亚
>
> **付款方式：** 代码 `0020` · 任意机构 · `account.type`: `S` · `beneficiary.bank.code` 尚未公布，请在上线前向您的客户经理确认正确的值。
>
> | 代码 | `account.details` | 说明 |
> | - | - | - |
> | `701` | `00000001` | `InvalidAccountNumber` |
> | `702` | `00000002` | InvalidAccountNumber - Account Closed |
> | `703` | `00000003` | InvalidAccountNumber - Account Blocked |
> | `640` | `00000004` | Transaction rejected by AML |
> | `833` | `00000005` | Error account does not accept transfers |

> [tab] 巴西
>
> **付款方式：** PIX，代码 `0031`
>
> PIX 付款通过 `beneficiary.bank.account.alias`（PIX 密钥）而非银行账号来识别收款人。下面的部分场景改用标准银行账户，以同时涵盖银行转账收款人。
>
> | 代码 | `account.details` | 说明 |
> | - | - | - |
> | `701` | `account.alias`: `00100000001` | `InvalidAccountNumber` |
> | `702` | 银行 `001` BCO DO BRASIL S.A. · `account.number`: `00001235-0` | InvalidAccountNumber - Account Closed |
> | `703` | 银行 `001` BCO DO BRASIL S.A. · `account.number`: `00001234-1`, `account.type`: `S` | InvalidAccountNumber - Account Blocked |
> | `640` | `account.alias`: `rejected.aml@sandbox.br` | Transaction rejected by AML |
> | `833` | `account.alias`: `00100000005` | Error account does not accept transfers |

> [tab] 智利
>
> **付款方式：** 代码 `0050` · **银行：** BANCO DE CHILE (`001`) · `account.type`: `S`
>
> | 代码 | `account.details` | 说明 |
> | - | - | - |
> | `701` | `001000000001` | `InvalidAccountNumber` |
> | `702` | `001000000002` | InvalidAccountNumber - Account Closed |
> | `703` | `001000000003` | InvalidAccountNumber - Account Blocked |
> | `640` | `001000000004` | Transaction rejected by AML |
> | `833` | `001000000005` | Error account does not accept transfers |
>
> `account.type` 可取 `S`（储蓄账户）、`C`（支票账户）或 `V`（vista）。

> [tab] 哥伦比亚
>
> 这些测试场景使用 ACH 通道（代码 `0060`）。任何机构都接受这些测试值。`account.type`: `S`。
>
> | 代码 | `account.details` | 说明 |
> | - | - | - |
> | `701` | `000000001` | `InvalidAccountNumber` |
> | `702` | `000000002` | InvalidAccountNumber - Account Closed |
> | `703` | `000000003` | InvalidAccountNumber - Account Blocked |
> | `640` | `000000004` | Transaction rejected by AML |
>
> 此场景改用 Bre-B（代码 `0062`）。`account.type`: `P`。
>
> | 代码 | `account.details` | 说明 |
> | - | - | - |
> | `833` | `+573000000005` | Error account does not accept transfers |

> [tab] 哥斯达黎加
>
> **付款方式：** 代码 `0070` · **银行：** BANCO DE COSTA RICA (`0152`) · `account.type`: `S` · `account.details` 为 IBAN（22 个字符）
>
> | 代码 | `account.details` | 说明 |
> | - | - | - |
> | `701` | `CR38015200000000000001` | `InvalidAccountNumber` |
> | `702` | `CR11015200000000000002` | InvalidAccountNumber - Account Closed |
> | `703` | `CR81015200000000000003` | InvalidAccountNumber - Account Blocked |
> | `640` | `CR54015200000000000004` | Transaction rejected by AML |
> | `833` | `CR27015200000000000005` | Error account does not accept transfers |

> [tab] 多明尼加共和国
>
> **付款方式：** 代码 `0080` · **银行：** BANCO BHD (`101012308`) · `account.details` 为 IBAN（28 个字符）
>
> | 代码 | `account.details` | 说明 |
> | - | - | - |
> | `701` | `DO13BAGR00000000000000000001` | `InvalidAccountNumber` |
> | `702` | `DO83BAGR00000000000000000002` | InvalidAccountNumber - Account Closed |
> | `703` | `DO56BAGR00000000000000000003` | InvalidAccountNumber - Account Blocked |
> | `640` | `DO29BAGR00000000000000000004` | Transaction rejected by AML |
> | `833` | `DO02BAGR00000000000000000005` | Error account does not accept transfers |

> [tab] 萨尔瓦多
>
> **付款方式：** 代码 `0100` · 任意机构 · `account.type`: `S` · `account.details` 为 IBAN（28 个字符）
>
> | 代码 | `account.details` | 说明 |
> | - | - | - |
> | `701` | `SV50ACAT00000000000000000001` | `InvalidAccountNumber` |
> | `702` | `SV23ACAT00000000000000000002` | InvalidAccountNumber - Account Closed |
> | `703` | `SV93ACAT00000000000000000003` | InvalidAccountNumber - Account Blocked |
> | `640` | `SV66ACAT00000000000000000004` | Transaction rejected by AML |
> | `833` | `SV39ACAT00000000000000000005` | Error account does not accept transfers |

> [tab] 危地马拉
>
> **付款方式：** 代码 `0110` · 任意机构 · `account.type`: `S` · `beneficiary.bank.code` 尚未公布，请在上线前向您的客户经理确认正确的值。
>
> | 代码 | `account.details` | 说明 |
> | - | - | - |
> | `701` | `0000000001` | `InvalidAccountNumber` |
> | `702` | `0000000002` | InvalidAccountNumber - Account Closed |
> | `703` | `0000000003` | InvalidAccountNumber - Account Blocked |
> | `640` | `0000000004` | Transaction rejected by AML |
> | `833` | `0000000005` | Error account does not accept transfers |

> [tab] 洪都拉斯
>
> **付款方式：** 代码 `0120` · 任意机构 · `account.type`: `S` · `beneficiary.bank.code` 尚未公布，请在上线前向您的客户经理确认正确的值。
>
> | 代码 | `account.details` | 说明 |
> | - | - | - |
> | `701` | `00000000001` | `InvalidAccountNumber` |
> | `702` | `00000000002` | InvalidAccountNumber - Account Closed |
> | `703` | `00000000003` | InvalidAccountNumber - Account Blocked |
> | `640` | `00000000004` | Transaction rejected by AML |
> | `833` | `00000000005` | Error account does not accept transfers |

> [tab] 墨西哥
>
> **付款方式：** SPEI，代码 `0130` · **银行：** BANAMEX (`002`) · `account.details` 为 CLABE（18 位数字）
>
> | 代码 | `account.details` | 说明 |
> | - | - | - |
> | `701` | `002180000000000012` | `InvalidAccountNumber` |
> | `702` | `002180000000000025` | InvalidAccountNumber - Account Closed |
> | `703` | `002180000000000030` | InvalidAccountNumber - Account Blocked |
> | `640` | `002180000000000041` | Transaction rejected by AML |
> | `833` | `002180000000000054` | Error account does not accept transfers |

> [tab] 巴拿马
>
> **付款方式：** 代码 `0150` · 任意机构 · `account.type`: `S` · `beneficiary.bank.code` 尚未公布，请在上线前向您的客户经理确认正确的值。
>
> | 代码 | `account.details` | 说明 |
> | - | - | - |
> | `701` | `000000000001` | `InvalidAccountNumber` |
> | `702` | `000000000002` | InvalidAccountNumber - Account Closed |
> | `703` | `000000000003` | InvalidAccountNumber - Account Blocked |
> | `640` | `000000000004` | Transaction rejected by AML |
> | `833` | `000000000005` | Error account does not accept transfers |

> [tab] 巴拉圭
>
> **付款方式：** 代码 `0160` · 任意机构 · `account.type`: `S` · `beneficiary.bank.code` 尚未公布，请在上线前向您的客户经理确认正确的值。
>
> | 代码 | `account.details` | 说明 |
> | - | - | - |
> | `701` | `000000000001` | `InvalidAccountNumber` |
> | `702` | `000000000002` | InvalidAccountNumber - Account Closed |
> | `703` | `000000000003` | InvalidAccountNumber - Account Blocked |
> | `640` | `000000000004` | Transaction rejected by AML |
> | `833` | `000000000005` | Error account does not accept transfers |

> [tab] 秘鲁
>
> **付款方式：** 代码 `0170` · **银行：** Interbank (`003`) · `account.type`: `S` · `account.details` 为 CCI（20 位数字）
>
> | 代码 | `account.details` | 说明 |
> | - | - | - |
> | `701` | `00300029183746555075` | `InvalidAccountNumber` |
> | `702` | `00300047392810555078` | InvalidAccountNumber - Account Closed |
> | `703` | `00300091827364777776` | InvalidAccountNumber - Account Blocked |
> | `640` | `00300053748291777777` | Transaction rejected by AML |
> | `833` | `00300062839471777776` | Error account does not accept transfers |

***

## 字段映射参考

上述测试账户会填充[创建付款](https://docs.localpayment.com/zh/reference/create-a-payout.md)中的标准 `beneficiary.bank` 对象：

| 字段 | 备注 |
| - | - |
| `beneficiary.bank.code` | 阿根廷、智利、哥伦比亚（ACH）和秘鲁必填。墨西哥（CLABE 已编码银行信息）或巴西 PIX 无需填写。 |
| `beneficiary.bank.account.number` | 大多数国家必填。当您改为在 `account.alias` 中发送 PIX 密钥（巴西）、秘鲁（Yape）、玻利维亚（Yape）或哥伦比亚（Bre-B）时，请不要填写。 |
| `beneficiary.bank.account.type` | `S`（储蓄账户）、`C`（支票账户）或 `V`（vista，仅限智利）。阿根廷、智利、哥伦比亚和秘鲁必填。使用 PIX 密钥（巴西）、秘鲁（Yape）、玻利维亚（Yape）或哥伦比亚（Bre-B）时不使用。 |
| `beneficiary.bank.account.alias` | 用于 PIX 密钥（巴西）、秘鲁（Yape）、玻利维亚（Yape）和哥伦比亚（Bre-B）。 |

通过校验位验证的账号（墨西哥 CLABE、阿根廷 CBU，以及哥斯达黎加、多明尼加共和国和萨尔瓦多使用的 IBAN 格式）是结构上有效的测试值，并非真实账户。它们的唯一用途是触发所映射的拒绝场景。

***

## 后续步骤

> [card] [通过银行转账汇款](https://docs.localpayment.com/zh/docs/send-funds-via-bank-transfer.md)
>
> 创建银行转账付款的完整 API 参考，包括各国具体要求。

> [card] [退货与召回](https://docs.localpayment.com/zh/docs/returns-and-recalls.md)
>
> 了解付款在 Production 中被拒绝或完成后被退回时会发生什么。


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