> ## 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 的 API 为客户生成虚拟账户。支持单笔和批量处理。

通过 Localpayment 的 API，以编程方式为您的客户生成虚拟账户。支持创建单个账户和批量处理多个账户。

## 开始之前

请确保您已备好：

> [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 以接收付款通知。

***

## 虚拟账户创建方法

我们提供灵活的虚拟账户创建方案，以满足不同的运营需求。您可以通过[**在线（API）**](https://docs.localpayment.com/zh/reference/create-virtual-account.md)和[**离线**](https://docs.localpayment.com/zh/docs/offline-virtual-account-creation.md)两种方式创建虚拟账户，无论选择哪种方式，您都可以使用两种创建模式：

* [**单个创建**](#option-1-individual-virtual-account-creation)：生成具有特定配置的单个虚拟账户，非常适合客户驱动的流程和需要按账户进行定制的场景。
* [**批量创建**](#option-2-create-virtual-accounts-in-batch)：在一次操作中处理多个虚拟账户，针对批量账户生成、大规模注册以及优先考虑处理效率的场景进行了优化。

| 国家/地区 | 在线的 | 离线 |
| :- | :- | :- |
| **[阿根廷](https://docs.localpayment.com/zh/docs/argentina.md)** | ✔ | ✔ |
| **[巴西](https://docs.localpayment.com/zh/docs/brazil.md)** | ✔ | — |
| **[智利](https://docs.localpayment.com/zh/docs/chile.md)** | ✔ | ✔ |
| **[哥伦比亚](https://docs.localpayment.com/zh/docs/colombia.md)** | ✔ | — |
| **[哥斯达黎加（CRC 和 USD）](https://docs.localpayment.com/zh/docs/costa-rica.md)** | ✔ | ✔ |
| **[墨西哥（SPEI、SPID 和 TEF）](https://docs.localpayment.com/zh/docs/mexico.md)** | ✔ | ✔ |
| [**秘鲁（PEN 和 USD）**](https://docs.localpayment.com/zh/docs/peru.md) | ✔ | — |

> [!WARNING]
>
> **重要的**
>
> 我们不接受现金存款。虚拟账户仅接收电子支付。任何通过银行网点、ATM 或其他渠道存入虚拟账户的现金，均不会记入商户账户。付款人必须使用其所在国家/地区支持的电子支付渠道，通过银行转账汇款。

***

## 受益人要求

了解受益人限制对于成功创建虚拟账户至关重要。每个国家/地区对于账户受益人都有具体规定，这会直接影响您如何构建支付流程。

### 各国居住要求

下表列出了各个国家接受的受益人类型：

<table>
  <thead>
    <tr>
      <th>
        国家/地区
      </th>

      <th>
        当地居民
      </th>

      <th>
        外国居民
      </th>

      <th>
        账户所有者
      </th>

      <th>
        别名
      </th>

      <th>
        银行转账显示名称
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        阿根廷
      </td>

      <td>
        ✅
      </td>

      <td>
        ✅
      </td>

      <td>
        * **FBO** = 外国居民
        * **DDA** = 当地居民
      </td>

      <td>
        最多可创建 1 个别名
      </td>

      <td>
        * **受益人姓名**（如为阿根廷公民，则在创建虚拟账户时提供）
        * **Localpayment 的法律实体名称**（所有其他情况）
      </td>
    </tr>

    <tr>
      <td>
        巴西
      </td>

      <td>
        ✅
      </td>

      <td>
        ✅
      </td>

      <td>
        * **FBO** = 外国居民
        * **DDA** = 当地居民
      </td>

      <td>
        不适用
      </td>

      <td>
        **Localpayment 的法律实体名称**
      </td>
    </tr>

    <tr>
      <td>
        智利
      </td>

      <td>
        ✅
      </td>

      <td>
        ✅
      </td>

      <td>
        **FBO**
      </td>

      <td>
        不适用
      </td>

      <td>
        **Localpayment 的法律实体名称**
      </td>
    </tr>

    <tr>
      <td>
        哥伦比亚
      </td>

      <td>
        ✅
      </td>

      <td>
        ✅
      </td>

      <td>
        **FBO**
      </td>

      <td>
        默认密钥
      </td>

      <td>
        **Localpayment 的法律实体名称**
      </td>
    </tr>

    <tr>
      <td>
        墨西哥
      </td>

      <td>
        ✅
      </td>

      <td>
        ✅
      </td>

      <td>
        **DDA** = 当地居民
      </td>

      <td>
        不适用
      </td>

      <td>
        **Localpayment 的法律实体名称**
      </td>
    </tr>

    <tr>
      <td>
        秘鲁
      </td>

      <td>
        ✅
      </td>

      <td>
        ✅
      </td>

      <td>
        **FBO**
      </td>

      <td>
        不适用
      </td>

      <td>
        **Localpayment 的法律实体名称**
      </td>
    </tr>

    <tr>
      <td>
        哥斯达黎加
      </td>

      <td>
        ✅
      </td>

      <td>
        ✅
      </td>

      <td>
        **FBO**
      </td>

      <td>
        不适用
      </td>

      <td>
        **Localpayment 的法律实体名称**
      </td>
    </tr>
  </tbody>
</table>

> [!NOTE]
>
> ###
>
> **注意事项**：
>
> * **账户所有者**是指在银行系统中登记的法定账户持有人姓名（即银行层面可见的姓名）。**FBO**（为受益人利益而开立）表示该账户以 Localpayment 的名义开立，资金用于最终客户的利益。**DDA**（活期存款账户）表示该账户直接以受益人的名义开立。
> * **别名**：指虚拟账户可以注册的别名数量（或别名类型）（如果支持）。
> * **银行转账显示名称**：指在向虚拟账户进行电子资金转账时，付款人看到的名称。

### 创建虚拟账户所需的受益人信息

**所需信息：**

* **受益人类型**：定义虚拟账户属于个人还是公司：
  * INDIVIDUAL：用于个人账户。
  * COMPANY：指商业/法人实体。
* **受益人姓名**：个人全名或法定商号。
* **受益人文件**：用于核实身份的官方身份信息。
* **地址**：受益人的完整地址。
* **网站**：受益人的网站网址。

***

## 各国具体要求

虚拟账户的实施细节因国家/地区而异。未明确提及的国家/地区均遵循标准流程，无需特殊要求。集成前请查看以下要求：

> [tab] 阿根廷
>
> | 属性 | 说明 |
> | - | - |
> | 服务水平协议付款确认 | 实时 24/7 |
> | 处理货币 | `ARS`（阿根廷比索） |
> | 最低交易金额 | 1.00 阿根廷比索 |
> | 最高交易金额 | 没有上限。 |
> | 本地账户格式 | Cuenta Virtual Uniforme (CVU) |
> | 清算所 | COELSA |
> | 虚拟账户上限 | 无限 |
> | 虚拟账户创建模型 | [在线的](#step-1-create-a-virtual-account)，[离线](https://docs.localpayment.com/zh/docs/offline-virtual-account-creation.md) |
>
> ### 账户格式
>
> 在阿根廷，CVU（Clave Virtual Uniforme）是由支付服务提供商 (PSP) 发行的虚拟账户使用的 22 位数字代码。
>
> **结构：**
>
> * 第 1-3 位：3 位数字 - 发行实体 (PSP) 代码。
> * 第 4-7 位：4 位数字 - PSP 中的账户类型标识符。
> * 第 8 位：1 位数字 - 验证数字（校验和）。
> * 第 9-21 位：13 位数字 - PSP 内的唯一账号。
> * 第 22 位：1 位数字 - 控制数字（校验和验证器）。
>
> **例子**：`0000003112345678901234`

> [tab] 巴西
>
> | 属性 | 说明 |
> | - | - |
> | 服务水平协议付款确认 | 实时 24/7 |
> | 处理货币 | `BRL`（巴西雷亚尔） |
> | 最低交易金额 | 巴西雷亚尔 0.01 |
> | 最高交易金额 | 1,000,000.00 巴西雷亚尔 |
> | 本地账户格式 | 银行代码、分行名称和账号（TED 和 Pix 均使用）。对于 Pix，付款人也可以使用 Pix 密钥（别名）。 |
> | 支持的存款方式 | **Pix** 和 **TED** |
> | 清算所 | Pix，TED |
> | 虚拟账户上限 | 无限 |
> | 虚拟账户创建模型 | [在线的](#step-1-create-a-virtual-account) |
>
> ### 账户格式
>
> 在巴西，每个虚拟账户都由一个 **Pix 密钥**（别名）标识，并通过 **Pix** 和 **TED** 两种渠道接收资金。这两种渠道都指向同一个底层账户，因此无论付款人使用哪种渠道，您的集成都会收到相同的 webhook 通知。
>
> **对于 TED 和 Pix 转账**，付款方可以使用 API 响应中的以下三个字段：
>
> * `beneficiary.bank.code` — 银行代码。
> * `beneficiary.bank.branch.code` — 分支机构（代理机构）代码。
> * `beneficiary.bank.account.number` — 账号。
>
> **仅对于 Pix**，付款人也可以改用 `beneficiary.bank.account.aliases` 中返回的 **Pix 密钥**（别名），无需其他字段。
>
> **Pix 密钥结构：**
>
> Pix 密钥可以是以下几种格式之一：
>
> * **手机号码**：10 位数字——受益人登记的手机号码。
> * **电子邮件地址**：受益人注册的电子邮件地址。
> * **随机密钥**：系统生成的字母数字字符串。
>
> **注意事项**：
>
> * 个人账户（PF）最多可注册 5 个 Pix 密钥，而企业账户（PJ）最多可注册 20 个。

> [tab] 智利
>
> > [!WARNING]
> >
> > 请注意当地银行的转账限额和安全规定，以免交易被拒。详细信息请参阅[智利国家指南](https://docs.localpayment.com/zh/docs/chile.md#banking-transaction-limits-and-rules)。
>
> | 属性 | 说明 |
> | - | - |
> | 服务水平协议付款确认 | 实时 24/7 |
> | 处理货币 | `CLP`（智利比索） |
> | 最低交易金额 | 智利比索 1.00 |
> | 最高交易金额 | 智利比索 7,000,000.00 |
> | 本地账户格式 | 账号（6至16位数字） |
> | 清算所 | CCA |
> | 虚拟账户上限 | 请联系您的客户经理 |
> | 虚拟账户创建模型 | [在线的](#step-1-create-a-virtual-account)，[离线](https://docs.localpayment.com/zh/docs/offline-virtual-account-creation.md) |

> [tab] 哥伦比亚
>
> | 属性 | 说明 |
> | - | - |
> | 服务水平协议付款确认 | 实时 24/7 |
> | 处理货币 | `COP`（哥伦比亚比索） |
> | 最低交易金额 | 1.00 哥伦比亚比索 |
> | 最高交易金额 | 12,110,000.00 哥伦比亚比索 |
> | 本地账户格式 | Sistema de Cuentas de Deposito (CUD) |
> | 清算所 | ACH Colombia |
> | 虚拟账户上限 | 无限 |
> | 虚拟账户创建模型 | [在线的](#step-1-create-a-virtual-account) |

> [tab] 哥斯达黎加
>
> | 属性 | SINPE - IN | SINPE USD - IN |
> | - | - | - |
> | 服务水平协议付款确认 | 实时 24/7 | 实时 24/7 |
> | 处理货币 | `CRC`（哥斯达黎加科朗） | `USD`（美元） |
> | 最低交易金额 | CRC 1.00 | 1.00 美元 |
> | 最高交易金额 | CRC 100,000,000,000.00 | 1,000,000,000,000.00 美元 |
> | 本地账户格式 | IBAN（22 个字符） | IBAN（22 个字符） |
> | 清算所 | SINPE (Banco Central de Costa Rica) | SINPE (Banco Central de Costa Rica) |
> | 虚拟账户上限 | 无限 | 无限 |
> | 虚拟账户创建模型 | [在线的](#step-1-create-a-virtual-account)，[离线](https://docs.localpayment.com/zh/docs/offline-virtual-account-creation.md) | [在线的](#step-1-create-a-virtual-account)，[离线](https://docs.localpayment.com/zh/docs/offline-virtual-account-creation.md) |
>
> > [!NOTE]
> >
> > **哥斯达黎加虚拟账户**
> >
> > * 在哥斯达黎加，虚拟账户一旦创建**便无法停用**。如需停止接收付款，请删除账户。
> > * IBAN 遵循以下格式：`CR` + 20 位数字（例如，`CR75090100056938278310`）。
> > * 根据 SINPE 的规定，超过 90 天没有任何交易活动的虚拟账户必须被停用。实际上，账户会在每月第一个星期二 00:00（哥斯达黎加时间）自动停用。

> [tab] 墨西哥
>
> | 属性 | SPEI | TEF | SPID |
> | :- | :- | :- | :- |
> | 服务水平协议付款确认 | 实时 24/7 | T+1 截止时间为下午 5 点（UTC-6） | 实时 24/7 |
> | 处理货币 | `MXN`（墨西哥比索） | `MXN`（墨西哥比索） | `USD`（美元） |
> | 最低交易金额 | 1.00 墨西哥比索 | 1.00 墨西哥比索 | 1.00 美元 |
> | 最高交易金额 | 1,000,000,000.00 墨西哥比索 | 1,000,000,000.00 墨西哥比索 | 10,000,000.00 美元 |
> | 本地账户格式 | 18 位 CLABE（Clave Bancaria Estandarizada） | 18 位 CLABE（Clave Bancaria Estandarizada） | 18 位 CLABE（Clave Bancaria Estandarizada） |
> | 清算所 | 墨西哥银行 | CECOBAN | 墨西哥银行 |
> | 虚拟账户上限 | 无限 | 无限 | 请联系您的客户经理 |
> | 付款人类型 | 个人和公司 | 个人和公司 | 公司 |
> | 虚拟账户创建模型 | [在线的](#step-1-create-a-virtual-account)，[离线](https://docs.localpayment.com/zh/docs/offline-virtual-account-creation.md) | [在线的](#step-1-create-a-virtual-account)，[离线](https://docs.localpayment.com/zh/docs/offline-virtual-account-creation.md) | [在线的](#step-1-create-a-virtual-account)，[离线](https://docs.localpayment.com/zh/docs/offline-virtual-account-creation.md) |
>
> > [!NOTE]
> >
> > **墨西哥 SPID**
> >
> > 如需申请通过墨西哥 SPID 系统进行美元转账的虚拟账户，请注意：
> >
> > * **可用银行**：请查阅[支持的银行列表和转账代码](https://docs.localpayment.com/zh/docs/mexico.md#bank-codes)。
> > * **Localpayment 账户**：您必须拥有美元 Localpayment 账户才能收款。如果您没有账户，请联系我们的客服团队进行设置，然后再继续操作。
>
> ### 账户格式
>
> 在墨西哥，虚拟账户必须使用标准化的 CLABE（Clave Bancaria Estandarizada）号码。
>
> **结构：**
>
> * 第 1-3 位：银行代码（由墨西哥银行分配）
> * 第 4-6 位：分支机构/办事处代码（地理位置）
> * 第 7-17 位：客户账号
> * 第 18 位：控制数字（校验和）
>
> 在墨西哥，以墨西哥比索（MXN）进行的本地银行转账主要通过两个清算系统进行：
>
> * **SPEI（Sistema de Pagos Electrónicos Interbancarios，银行间电子支付系统）**：是由墨西哥银行运营的实时银行间支付系统，可在数秒内完成银行间的资金转账。交易通常即时结算，账户必须使用标准化的 CLABE 号码进行识别。
>
> * \*\*TEF（Transferencia Electrónica de Fondos，电子资金转账）：\*\*墨西哥的一种支付方式，由 CECOBAN 运营，用于银行间转账，交易将在下一个工作日处理。它需要使用标准化的 CLABE 账号进行识别，仅在墨西哥银行规定的工作日可用，通常用于对时间要求不高的付款，例如定期供应商付款或无需立即结算的定期转账。
>
> 对于墨西哥银行账户之间的美元 (USD) 转账，我们提供 SPID 服务。
>
> * \*\*SPID（Sistema de Pagos Interbancarios en Dolares，墨西哥银行间美元转账系统）\*\*是墨西哥专门用于国内银行间美元转账的支付系统。它使总部位于墨西哥的公司能够在墨西哥境内不同银行的账户之间高效地转移美元资金。
>
> **SPID** 的工作原理：
>
> * \*\*处理时间：\*\*墨西哥银行工作日，上午 8:00 至下午 5:00（UTC-6）。交易将全天分批处理。
>
> * \*\*账户要求：\*\*交易使用收款人美元账户的标准化 CLABE 号码进行处理。
>
> * \*\*典型应用：\*\*最适合 B2B 支付、国际供应商结算以及其他资金必须以美元结算的企业财务运作。

> [tab] 秘鲁
>
> | 属性 | CCI-In | CCI-In（美元） |
> | - | - | - |
> | 服务水平协议付款确认 | 实时 24/7 | 实时 24/7 |
> | 处理货币 | `PEN`（秘鲁索尔） | `USD`（美元） |
> | 最低交易金额 | 秘鲁索尔 1.00 | 1.00 美元 |
> | 最高交易金额 | 30,000.00 秘鲁索尔 | 10,000.00 美元 |
> | 本地账户格式 | Codigo de Cuenta Interbancario (CCI) | Codigo de Cuenta Interbancario (CCI) |
> | 清算所 | CCE | CCE |
> | 虚拟账户上限 | 无限 | 无限 |
> | 虚拟账户创建模型 | [在线的](#step-1-create-a-virtual-account) | [在线的](#step-1-create-a-virtual-account) |
>
> > [!WARNING]
> >
> > **重要的：**
> >
> > * 您的虚拟账户的货币（PEN 或 USD）由您的 Localpayment 账户配置决定。
> >
> > * 如果您需要向您的虚拟账户充值超过 30,000 PEN，您必须联系我们的[支持团队](mailto:support@localpayment.com)。
>
> ### 账户格式
>
> 在秘鲁，虚拟账户使用 CCI（Código de Cuenta Interbancario）格式，这是一种标准化的 20 位银行间账户代码。
>
> **结构：**
>
> * 第 1-3 位：3 位数字 - 银行代码（由 SBS - Superintendencia de Banca, Seguros y AFP 分配）
> * 第 4-6 位：3 位数字 - 分行编号
> * 第 7-18 位：12 位数字 - 银行内部的唯一账号
> * 第 19-20 位：2 位数字 - 控制数字（校验和验证器）
>
> **例子**：`92250610000000101419`

***

## 第一步：创建虚拟账户

### 方案一：创建个人虚拟账户

创建具有详细配置的单一虚拟账户，用于特定客户或交易。

要创建虚拟账户，您需要向 [创建虚拟账户](https://docs.localpayment.com/zh/reference/create-virtual-account.md) endpoint 发送 `POST` 请求。

#### 关键请求参数

该请求需要几个关键参数：

| 参数 | 说明 | 必需的 |
| - | - | - |
| externalId | 商家分配的用于引用虚拟账户的唯一标识符。 | ✅ |
| accountNumber | 虚拟账户将关联或绑定的商户账号。 | ✅ |
| country | 虚拟账户开通的国家/地区。 | ✅ |
| beneficiary | 包含受益人个人信息的对象（受益人类型、姓名、证件、地址、网站）。 | ✅ |

#### 示例请求

以下是一个使用 `curl` 的示例：

```bash curl theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
curl --request POST \
     --url https://api.stage.localpayment.com/api/virtual-account \
     --header 'Authorization: Bearer <your_access_token>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "country": "ARG",
  "beneficiary": {
    "type": "COMPANY",
    "document": {
      "id": "30-71234567-9",
      "type": "CUIT"
    },
    "name": "ACME INTERNATIONAL LTD",
    "lastName": "",
    "fullName": "ACME INTERNATIONAL LTD",
    "address": {
      "street": "Av. Corrientes",
      "number": "1234",
      "city": "Buenos Aires",
      "state": "CABA",
      "country": "Argentina"
    },
    "website": "https://yongxin.technology.com"
  },
  "externalId": "de14bcf2-15ee-22e3-ab59-99c3fcba31e8",
  "accountNumber": "{{accountNumber}}"
}
'
```

查看请求中所有 [可用的参数](https://docs.localpayment.com/zh/reference/create-virtual-account.md)。

#### 成功响应

请求成功后，API 将返回状态码 `100`，账户状态初始设置为 `INPROGRESS`。虚拟账户在激活期间将保持此状态，激活过程完成后将转换为 [可用状态](https://docs.localpayment.com/zh/docs/get-virtual-account-status.md) 之一。

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "externalId": "de14bcf2-15ee-22e3-ab59-99c3fcba31e8",
  "internalId": "5ba31ea0-669b-43f6-88a1-1601f3cade0a",
  "accountNumber": "{{accountNumber}}",
  "country": "ARG",
  "currency": "ARS",
  "beneficiary": {
    "type": "COMPANY",
    "name": "ACME INTERNATIONAL LTD",
    "fullName": "ACME INTERNATIONAL LTD",
    "lastName": "",
    "document": {
      "type": "CUIT",
      "id": "30-71234567-9"
    },
    "address": {
      "street": "Av. Corrientes",
      "number": "1234",
      "city": "Buenos Aires",
      "state": "CABA",
      "country": "Argentina"
    }
  },
  "status": {
    "code": "100",
    "description": "INPROGRESS",
    "detail": "Virtual account in progress"
  },
  "errors": []
}
```

#### 关键响应字段

| 字段 | 说明 |
| - | - |
| `externalId` | 系统中用于标识交易的唯一标识符。**它将用于执行其他操作，例如获取虚拟账户状态**。 |
| `internalId` | Localpayment 系统中交易的唯一标识符。 |
| `status` | 包含虚拟账户状态信息的对象。 |
| `status.code` | 状态码（例如，`100` 对应 `INPROGRESS`）。 |
| `date.processedDate` | 交易开始处理时。 |

#### 错误响应

请求失败时，您将收到详细的错误信息：

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "externalId": "f5c4529e-67c1-43e0-bc2a-97250e736c98",
  "internalId": "f2d9d9b0-093d-469b-c8d6-728b0cc67e80",
  "status": {
    "code": "300",
    "description": "REJECTED",
    "detail": "Invalid param + [document.id] + verification failed"
  },
  "errors": [
    {
      "code": "300",
      "detail": "Invalid param + [document.id] + verification failed"
    }
  ]
}
```

#### 账户激活时间

虚拟账户的激活时间因国家/地区而异。以下是账户激活并可以接收付款的预计时间：

* **阿根廷**：最多 6 秒
* **巴西**：最多 15 分钟
* **智利**：最多 6 秒
* **哥伦比亚**：最多 6 秒
* **墨西哥**：最多 6 秒
* **秘鲁**：最多 6 秒

### 方案二：批量创建虚拟账户

通过单个 API 请求生成多个虚拟账户，实现高效的批量操作。要批量创建虚拟账户，您需要向 [批量创建虚拟账户](https://docs.localpayment.com/zh/reference/request-batch.md) endpoint 发送 `POST` 请求。

> [!NOTE]
>
> ###
>
> 一次批量请求只能创建同一国家/地区的账户。

#### 关键请求参数

该请求需要几个关键参数：

| 参数 | 说明 | 必需的 |
| - | - | - |
| externalId | 商家分配的用于引用虚拟账户的唯一标识符。 | ✅ |
| accountNumber | 虚拟账户将关联或绑定的商户账号。 | ✅ |
| country | 虚拟账户开通的国家/地区。 | ✅ |
| beneficiary | 包含受益人个人信息的对象。 | ✅ |
| accounts | 包含与虚拟账户关联的各个子账户及其各自受益人的数组。 | |

#### 示例请求

以下是一个使用 `curl` 的示例：

```bash curl theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
curl --request POST \
     --url https://api.stage.localpayment.com/api/virtual-account-batch \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'Authorization: Bearer <your_access_token>' \
     --data '
{
  "externalId": "f059a032-9253-4607-9b8e-2948ed18d595",
  "accountNumber": "{{accountNumber}}",
  "country": "MEX",
  "name": "Virtual Account",
  "accounts": [
    {
      "externalId": "9210b519-5c29-4419-8d28-04f7543a914f",
      "beneficiary": {
        "type": "INDIVIDUAL",
        "name": "John",
        "lastname": "Doe",
        "document": {
          "id": "EXTF900101NI1",
          "type": "RFC"
        }
      }
    },
    {
      "externalId": "e4914217-41bc-49a5-b2f8-df950bf9bae7",
      "beneficiary": {
        "type": "INDIVIDUAL",
        "name": "Alicia",
        "lastname": "Doe",
        "document": {
          "id": "EXTF900101NI2",
          "type": "RFC"
        }
      }
    }
  ]
}
'
'
```

查看请求中所有 [可用的参数](https://docs.localpayment.com/zh/reference/request-batch.md)。

#### 成功响应

请求成功后，API 将返回状态码 `100`，账户状态设置为 `INPROGRESS`。

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "externalId": "f059a032-9253-4607-9b8e-2948ed18d595",
  "internalId": "1748f8f8-dcac-4547-b3fb-7d6529245d84",
  "accountNumber": "{{accountNumber}}",
  "status": {
    "code": "100",
    "description": "INPROGRESS",
    "detail": "Batch Process Virtual Account in progress"
  },
  "comment": "For obtaining the asynchronous response, kindly submit a request to the service after a brief interval. GET {api_environment_url}/api/virtual-account-batch/7facbbbf-d279-4ab5-9aeb-7583fa3f35ec"
}
```

#### 关键响应字段

| 字段 | 说明 |
| - | - |
| `externalId` | 系统中用于标识交易的唯一标识符。**它将用于执行其他操作，例如获取虚拟账户状态**。 |
| `internalId` | Localpayment 系统中交易的唯一标识符。 |
| `status` | 包含虚拟账户状态信息的对象。 |
| `status.code` | 状态码（例如，`100` 对应 `INPROGRESS`）。 |
| `date.processedDate` | 交易开始处理时。 |

#### 错误响应

请求失败时，您将收到详细的错误信息：

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "timestamp": "2025-01-03T22:03:39.657+00:00",
  "status": 400,
  "error": "Bad Request.",
  "message": "External ID already used - Duplication",
  "path": "/virtual-account/batch"
}
```

有关状态代码及其含义的完整列表，请参阅 [交易状态](https://docs.localpayment.com/zh/reference/get-transaction-status.md) 文档。

***

## 步骤 2. 跟踪虚拟账户状态

监控虚拟账户状态对于维持最佳支付运营至关重要。Localpayment 通过统一的 API 接口和实时状态更新，为单个账户和批量创建的账户提供全面的跟踪功能。

> [card] [个人虚拟账户](https://docs.localpayment.com/zh/docs/get-virtual-account-status.md#method-1-check-individual-virtual-account-status)
>
> 要检查单个虚拟账户的状态，您需要向 [获取虚拟账户状态](https://docs.localpayment.com/zh/reference/get-virtual-account-status.md) endpoint 发送 `GET` 请求。

> [card] [针对批量创建的账户](https://docs.localpayment.com/zh/docs/get-virtual-account-status.md#method-2-check-batch-virtual-account-status)
>
> 要监控批量创建的虚拟账户的处理状态，您需要向 [获取虚拟账户状态（批量）](https://docs.localpayment.com/zh/reference/get-virtual-account-status-batch.md) endpoint 发送 `GET` 请求。

## 后续步骤

> [card] [跟踪虚拟账户状态](https://docs.localpayment.com/zh/docs/get-virtual-account-status.md)
>
> 监控虚拟账户的生命周期，以确保最佳的支付运营。了解不同的账户状态类型，并理解每种状态对您的支付处理能力的影响。

> [card] [付款说明](https://docs.localpayment.com/zh/docs/payment-instructions.md)
>
> 请向付款方提供“获取虚拟账户状态”API 响应中返回的正确收款人信息，以便正确处理付款。请查看特定国家/地区的说明，以确保准确合规地执行付款。

> [card] [启用/禁用虚拟账户](https://docs.localpayment.com/zh/docs/activate-deactivate-virtual-account.md)
>
> 通过临时激活或停用虚拟账户来管理账户可用性。这对于季节性业务、账户维护或临时暂停账户非常有用。

> [card] [删除虚拟账户](https://docs.localpayment.com/zh/docs/delete-virtual-account.md)
>
> 永久停用虚拟账户。此操作将阻止所有未来向该账户的付款，但会保留其完整的交易记录。此操作不可逆。适用于不再需要的账户；如需恢复使用，请创建新账户。


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