> ## 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 Business Portal**：用户友好的界面，方便[手动交易管理](https://docs.localpayment.com/zh/docs/internal-transfers)。
* **API 集成**：通过程序化方式实现自动支付处理。

本指南重点介绍 API 实现，涵盖从初始化到完成的完整流程。

## 开始之前

请确保您已备好：

* 有效的 [API 凭证](https://docs.localpayment.com/zh/docs/api-keys-and-environments.md)（访问令牌）。
* 完整的受益人信息。
* 为目标国家/地区正确[设置](https://docs.localpayment.com/zh/docs/setup-guide.md)账户。
* 了解特定国家/地区的要求（见下文[“国家/地区要求”](#country-specific-requirements)）。

***

## 步骤 1：初始化支付交易

要创建银行转账付款，请向 **[Create a Payout](https://docs.localpayment.com/zh/reference/create-a-payout.md)** endpoint 发送 `POST` 请求，并将 `paymentMethod.type` 设置为 `"BankTransfer"`。

### endpoint

```
POST https://api.stage.localpayment.com/api/payout/
```

### 必需的标头

```http theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
Authorization: Bearer <your_access_token>
```

### 关键请求参数

该请求需要几个关键对象：

| 对象 | 描述 | 必需的 |
| - | - | - |
| `beneficiary` | 收款人详细信息，包括银行信息 | ✅ |
| `sender` | 发件人信息（用于合规性） | ✅ |
| `merchant` | 商家/企业详情 | ✅ |
| `paymentMethod` | 支付方式配置 | ✅ |
| `amount` | 交易金额 | ✅ |
| `currency` | 交易货币代码 | ✅ |
| `country` | 目标国家/地区代码 | ✅ |

### 示例请求（阿根廷）

```bash curl theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
curl --request POST \
     --url https://api.stage.localpayment.com/api/payout/ \
     --header 'Authorization: Bearer <your_access_token>' \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json' \
     --data '[
 {
  "externalId": "212407f5-0c86-4687-91e4-df3ab8a513ab",
  "country": "ARG",
  "currency": "ARS",
  "amount": 500.18,
  "paymentMethod": {
    "type": "BankTransfer",
    "code": "0010",
    "flow": "DIRECT"
  },
  "beneficiary": {
    "name": "John",
    "lastName": "Doe",
    "type": "INDIVIDUAL",
    "document": {
      "type": "CUIT",
      "id": "20907920276"
    },
    "userReference": "Test",
    "email": "john.doe@email.com",
    "phone": {
      "countryCode": "54",
      "areaCode": "11",
      "number": "12345678"
    },
    "birthDate": "2021-11-08",
    "nationality": "Argentine",
    "address": {
      "street": "Avenida Principal",
      "number": "234",
      "city": "La Plata",
      "state": "Buenos Aires",
      "country": "Argentina",
      "zipCode": "C1420",
      "comment": "TEST"
    },
    "bank": {
      "name": "BANCO DE GALICIA Y BUENOS AIRES S.A.U.",
      "code": "007",
      "account": {
        "number": "0070145330004020870169",
        "type": "S"
      }
    }
  },
  "sender": {
    "type": "INDIVIDUAL",
    "name": "David",
    "lastName": "Doe",
    "document": {
      "type": "CUIT",
      "id": "20907920276"
    },
    "userReference": "Test",
    "email": "david.doe@email.com",
    "phone": {
      "countryCode": "54",
      "areaCode": "11",
      "number": "12345678"
    },
    "birthDate": "2021-11-08",
    "nationality": "Argentine",
    "address": {
      "street": "Avenida Principal",
      "number": "234",
      "city": "La Plata",
      "state": "Buenos Aires",
      "country": "Argentina",
      "zipCode": "C1420",
      "comment": "TEST"
    }
  },
  "merchant": {
    "type": "COMPANY",
    "name": "Company Name",
    "document": {
      "type": "CUIT",
      "id": "20907920276"
    },
    "userReference": "Test",
    "email": "company@email.com",
    "phone": {
      "countryCode": "54",
      "areaCode": "11",
      "number": "12345678"
    },
    "birthDate": "2021-11-08",
    "nationality": "Argentine",
    "address": {
      "street": "Avenida Principal",
      "number": "234",
      "city": "La Plata",
      "state": "Buenos Aires",
      "country": "Argentina",
      "zipCode": "C1420",
      "comment": "TEST"
    }
  },
  "accountNumber": "{{accountNumber}}",
  "conceptCode": "0039",
  "comment": "ARG TEST",
  "requireAuth": true
}
]'
```

***

## 步骤 2：处理响应

### 成功响应

成功的响应应包含详细的交易信息和跟踪标识符：

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
    "externalId": "212407f5-0c86-4687-91e4-df3ab8a513ab",
    "internalId": "095a5d8d-53ff-4a8d-9665-7ceb6eaa94df",
    "paymentMethod": {
        "code": "0010",
        "name": "INTERBANKING",
        "description": "string",
        "paymentMethodType": "BankTransfer"
    },
    "country": "ARG",
    "currency": "ARS",
    "amount": 500.18,
    "accountNumber": "{{accountNumber}}",
    "clientCode": "0001",
    "clientName": "Acme",
    "status": {
        "code": "104",
        "description": "PendingAuth",
        "detail": "The payout is pending of authorization by client"
    },
    "beneficiary": {
        "bank": {
            "name": "BANCO DE GALICIA Y BUENOS AIRES S.A.U.",
            "code": "007",
            "countryISOCode3": null,
            "branch": null,
            "account": {
                "number": "0070145330004020870169",
                "type": "S",
                "alias": null,
                "pixKey": null,
                "phone": null
            }
        },
        "type": "INDIVIDUAL",
        "name": "John",
        "lastname": "Doe",
        "document": {
            "type": "CUIT",
            "id": "20907920276"
        },
        "userReference": "Test",
        "email": "john.doe@email.com",
        "phone": {
            "countryCode": "54",
            "areaCode": "11",
            "number": "12345678"
        },
        "birthdate": "2021-11-08T00:00:00Z",
        "nationality": "Argentine",
        "address": {
            "street": "Avenida Principal",
            "number": "234",
            "city": "La Plata",
            "state": "Buenos Aires",
            "country": "Argentina",
            "zipCode": "C1420",
            "comment": "TEST"
        }
    },
    "merchant": {
        "type": "COMPANY",
        "name": "Company Name",
        "lastname": null,
        "document": {
            "type": "CUIT",
            "id": "20907920276"
        },
        "userReference": "Test",
        "email": "company@email.com",
        "phone": {
            "countryCode": "54",
            "areaCode": "11",
            "number": "12345678"
        },
        "birthdate": "2021-11-08T00:00:00Z",
        "nationality": "Argentine",
        "address": {
            "street": "Avenida Principal",
            "number": "234",
            "city": "La Plata",
            "state": "Buenos Aires",
            "country": "Argentina",
            "zipCode": "C1420",
            "comment": "TEST"
        }
    },
    "sender": {
        "type": "INDIVIDUAL",
        "name": "David",
        "lastname": "Doe",
        "document": {
            "type": "CUIT",
            "id": "20907920276"
        },
        "userReference": "Test",
        "email": "david.doe@email.com",
        "phone": {
            "countryCode": "54",
            "areaCode": "11",
            "number": "12345678"
        },
        "birthdate": "2021-11-08T00:00:00Z",
        "nationality": "Argentine",
        "address": {
            "street": "Avenida Principal",
            "number": "234",
            "city": "La Plata",
            "state": "Buenos Aires",
            "country": "Argentina",
            "zipCode": "C1420",
            "comment": "TEST"
        }
    },
    "comment": "ARG TEST",
    "exchangeRateToken": null,
    "date": {
        "creationDate": "2025-10-10T21:04:44.2729228Z",
        "processedDate": "2025-10-10T21:04:44.2731812Z"
    },
    "errors": null,
    "internalLoteID": "151840"
}
```

### 关键响应字段

| 字段 | 描述 | 用例 |
| - | - | - |
| `internalId` | Localpayment 的唯一交易标识符 | 交易跟踪和支持 |
| `externalId` | 您的参考编号 | 内部对账 |
| `status.code` | 当前交易状态代码 | 状态监控 |
| `date.creationDate` | 交易创建时 | 审计跟踪 |
| `date.processedDate` | 交易开始处理时 | 处理时间计算 |

### 错误响应

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

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
[
  {
    "externalId": "1736488884",
    "internalId": "cd052d8c-8406-45f8-98aa-aff9876c3285",
    "status": {
      "code": "801",
      "description": "Rejected",
      "detail": "Params error"
    },
    "errors": [
      {
        "code": "300",
        "description": "Invalid param + [paymentMethod.code] + doesn't exist for PAYMENT_METHOD_TYPE BankTransf"
      },
      {
        "code": "300",
        "description": "Invalid param + [beneficiary.document.id] + doesn´t match regex ^(20|23|24|25|26|27|30|33|34)-?\\d{2}[.]?\\d{3}[.]?\\d{3}-?\\d$"
      }
    ],
    "comment": "Addicional informetion"
  }
]
```

***

## 步骤 3：跟踪交易状态

提交付款申请后，可通过以下方式监控付款进度：

> [card] [Webhooks（推荐）](https://docs.localpayment.com/zh/docs/webhooks.md)
>
> 交易状态变更时接收实时通知。最适用于生产环境。

> [card] [状态 API endpoint](https://docs.localpayment.com/zh/reference/get-transaction-status.md)
>
> 以编程方式查询交易状态。可用于轮询或恢复丢失的 webhook 通知。

> [card] [Business Portal 视图](https://docs.localpayment.com/zh/docs/dashboard-overview.md)
>
> 用于监控交易的可视化界面。非常适合人工监督和详细的交易分析。

### 常用状态码

| 代码 | 状态 | 描述 |
| :- | :- | :- |
| `100` | `Received` | 已收到款项。 |
| `101` | `Locked` | 款项已确认支付，并通过了反洗钱验证。 |
| `102` | 进行中 | 款项已汇入银行账户。 |
| `104` | `PendingAuth` | 款项尚待客户授权后方可支付。 |
| `200` | `Completed` | 款项已从账户中扣除。 |
| `300` | `Rejected` | 无效参数 + \[参数名称] + \[原因]。 |

> [!NOTE]
>
> **完整参考**
>
> 请查看我们的[交易状态文档](https://docs.localpayment.com/zh/reference/transaction-status-error-codes)，了解所有状态代码。

***

## 第四步：交易审批

为了提高安全性，某些交易需要[两人批准](https://docs.localpayment.com/zh/docs/approvals-and-double-signature.md)：

1. **发起人**：提交付款请求。
2. **审批人**：审核并确认交易。

该流程可通过[Business Portal](https://docs.localpayment.com/zh/docs/dashboard-review-payout.md)或 [API endpoint](https://docs.localpayment.com/zh/reference/authorize-payout.md)进行管理。

> [!NOTE]
>
> **安全须知**
>
> 审批要求有助于防止未经授权的交易，并确保符合当地法规。

***

## 各国具体要求

具体实施方案因国家/地区而异。未明确提及的国家/地区均遵循标准流程，无需特殊要求。集成前请仔细阅读以下要求：

> [tab] 巴西
>
> **特殊要求：**
>
> * 当您使用账号（`beneficiary.bank.account.number`）发送付款时，`beneficiary.bank.branch` 为**必填项**。这适用于向账户发起的 TED 和 Pix 转账。如果省略该字段，付款将被拒绝，并返回错误 300（`beneficiary.bank.branch` must not be null）和错误 701（Invalid bank branch code）。
>   * `code`：**必填。** 银行要求格式的分行代码。
>   * `name`：**可选。** 银行分行的全称。
> * 当您使用 Pix 密钥（`beneficiary.bank.account.alias`）发送付款时，`beneficiary.bank.branch` 为可选项。
> * `merchant.address` 为**必填项**，且必须包含 `country`。
>   * `country`：**必填。** 商户地址的 3 位 ISO 国家代码（例如 `BRA`）。
>   * `merchant.address` 的其他字段为可选项。
>
> **使用 Chave Pix 汇款：**
>
> 除了传统的银行账户信息外，您还可以使用 Pix 密钥进行转账。Pix 是巴西的即时支付系统，支持全天候 24 小时转账，包括周末和节假日。
>
> 使用此方法：
>
> 1. 收件人必须拥有已注册的 Pix 密钥。
> 2. 您必须在 `beneficiary.bank.account.alias` 属性中提供此密钥。
>
>    \*\*注意：\*\*请求中必须排除 beneficiary.bank.account.type 和 beneficiary.bank.account.number 属性。
>
> **支持的 Pix 密钥类型：**
>
> 您可以使用以下五种密钥类型中的任意一种：
>
> * CPF（个人纳税人登记处）
> * CNPJ（国家法人实体登记处）
> * 手机号码
> * 电子邮件
> * 随机密钥：由中央银行生成的唯一32位字符代码。此选项允许收款人无需提供个人信息即可接收付款。

> [tab] 智利
>
> **特殊要求：**
>
> * 当货币设置为 智利比索 (**CLP**)时，金额必须以整数形式指定，不允许使用小数。

> [tab] 哥伦比亚
>
> 可用银行取决于所选的支付方式。哥伦比亚支持三种支付通道：ACH（`0060`）、Transfiya（`0061`）和 Bre-B（`0062`）。
>
> **Transfiya (`0061`)**
>
> > [!NOTE]
> >
> > Transfiya 通过**手机号码**识别收款人。这与 ACH（`0060`）不同，后者需要银行账号和银行代码。
>
> Transfiya 使用收款人注册的手机号码进行支付。支付发起后，收款人会收到短信通知，并可通过其银行应用程序接受或拒绝转账。
>
> | 字段 | 值 |
> | - | - |
> | `beneficiary.bank.account.type` | `"P"` |
> | `beneficiary.bank.account.number` | 以 `+573` 开头的 12 位字符串 |
>
> **支持的机构：**
>
> * BANCO AGRARIO DE COLOMBIA
> * BANCO COOPERATIVO COOPCENTRAL DIGITAL
> * BANCO CREZCAMOS
> * BANCO DE LAS MICROFINANZAS BANCAMIA SA
> * 法拉贝拉银行
> * BANCO FINANDINA
> * BANCO ITAÚ
> * BANCO POWWI
> * BANCO SERFINANZA
> * BANCOCOOPCENTRAL
> * Bancolombia
> * CFA COOPERATIVA FINANCIERA
> * CONFIAR COOPERATIVA FINANCIERA
> * 达维维恩达
> * MOVII
> * NEQUI
>
> **目前不支持：**
>
> * Banco AV Villas（服务时断时续）
> * Banco de Bogotá
> * Banco de Occidente SA
> * Dale
> * Davibank
>
> ***
>
> **Bre-B (`0062`)**
>
> Bre-B是哥伦比亚的即时支付系统，用于金融机构之间的实时转账。它使用简单的标识符（例如电话号码或身份证号码）而不是完整的银行账户信息。
>
> 开始之前，请查阅[可用的银行列表](https://docs.localpayment.com/zh/docs/colombia.md)，以确认哪些机构支持 Bre-B。
>
> 使用此方法：
>
> 1. 收款人必须拥有在银行注册的 Bre-B 密钥。
>
> 2. 在 `beneficiary.bank.account.alias` 中提供密钥。
>
> > [!NOTE]
> >
> > 使用 Bre-B 时，请在请求中排除 `beneficiary.bank.account.type` 和 `beneficiary.bank.account.number`。
>
> 支持的 Bre-B 密钥类型：
>
> * **身份证明文件** ——身份证、移民卡、公民卡或护照
> * **商户代码**
> * **手机号码**
> * **电子邮件**
> * **字母数字密钥** ——由银行生成的唯一代码（例如 `@alphamunKey01`），无需提供个人信息即可付款
>
> 在发送付款之前，您可以选择检查 Bre-B 密钥是否处于激活状态，并查看其经过掩码处理的所有者详细信息。请参阅[验证付款别名](https://docs.localpayment.com/zh/docs/verify-a-payout-alias.md)。

> [tab] 多明尼加共和国
>
> **特殊要求：**
>
> * `beneficiary.bank.account.number` 可以采用国内格式或 IBAN 格式提供。两者代表同一个底层账户。
>   * **国内格式：** 标准的国内账号。
>     示例：830640009
>   * **IBAN 格式：** 28 位字符的国际标准。多明尼加共和国的 IBAN 以“DO”开头。
>     示例：DO42BPDO00000000000830640009

> [tab] 墨西哥
>
> **特殊要求：**
>
> * `beneficiary.document.type` 为可选项。
> * 手机号码支付规范：
>   * `beneficiary.bank.account.type`：必须设置为“P”。
>   * `beneficiary.bank.account.number`：必须是 10 位数字。

> [tab] 秘鲁
>
> **特殊要求：**
>
> * 要验证 **CCI**，我们建议使用秘鲁银行提供的官方资源：
>   [https://www.transferenciasinterbancarias.pe/](https://www.transferenciasinterbancarias.pe/)

***

## 测试您的集成

### 沙盒环境

使用测试环境：

```
https://api.stage.localpayment.com/api/payout/
```

### 测试场景

请确认您的集成方案能够处理以下场景：

1. **交易成功**：标准支付流程
2. **验证错误**：无效的银行账户，缺少字段
3. **处理延迟**：需要时间处理的事务
4. **交易失败**：资金不足、收款人被冻结
5. **状态更新**：Webhook 处理和状态轮询

***

## 资源与后续步骤

利用这些关键资源，最大限度地提高您的集成成功率。

> [card] [Webhook 集成](https://docs.localpayment.com/zh/docs/webhooks.md)
>
> 设置交易状态更新的实时通知。

> [card] [报告 Business Portal](https://docs.localpayment.com/zh/docs/balance-report.md)
>
> 获取详细的分析、报告工具和对账功能。

> [card] [交易监控](https://docs.localpayment.com/zh/reference/transaction-status-error-codes)
>
> 学习查询交易状态并实现全面跟踪。

> [card] [API 参考](https://docs.localpayment.com/zh/reference/exchange-bulk.md)
>
> 提供包含交互式示例的完整 endpoint 文档。

> [!NOTE]
>
> **专业提示**
>
> 在部署到生产环境之前，务必先在我们的沙盒环境中测试您的工作流程。这可以确保您的错误处理、Webhook 处理和状态跟踪在所有场景下都能正常工作。

***

> [!NOTE]
>
> **需要帮助吗？**
>
> 如果您遇到任何问题或需要集成方面的帮助，请联系我们的[支持团队](mailto:support@localpayment.com)。


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