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

# Wire Out

Localpayment 允许您通过 API 集成和 Business Portal 界面，从您的 Localpayment 账户提取资金并存入您自己的外部银行账户。本指南涵盖用于资金结算的完整 Wire Out 工作流程，详细介绍授权流程、API 实现和状态跟踪。

> [!NOTE]
>
> **Wire Out 与付款**
>
> **Wire Out** 是**结算/提款**：资金从您的 Localpayment 账户转移到**您自己的外部银行账户**，绝不会转移到第三方。
>
> **付款**是**向最终收款人（通常是您的客户）支付款项**。如果您需要向第三方汇款，请改用[创建付款](https://docs.localpayment.com/zh/reference/create-a-payout.md)endpoint。

## 开始之前

请确保您已备好：

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

### 额外的 Wire Out 要求：

* 您的 Localpayment 账户中需有充足的**可用余额**。可在[余额报告](https://docs.localpayment.com/zh/docs/balance-report.md)中查看，或通过[预计余额报告](https://docs.localpayment.com/zh/docs/projected-balance-report.md)估算即将到账的资金。
* 具有**足够权限**进行 Wire Out 授权的用户角色（请参阅有关角色和权限的文档）。
* **外部银行账户详情**（SWIFT 代码、账号、收款人信息）。

***

## 实施指南

Localpayment 提供两种处理 Wire Out 的方法：用于自动处理的 API 集成，以及用于手动操作的 Business Portal。

> [card] [API Wire Out 处理](#process-wire-out-via-api)
>
> 通过 REST API 以编程方式发起 Wire Out 交易，
> 用于自动化结算工作流程和系统集成。

> [card] [Business Portal Wire Out 处理](https://docs.localpayment.com/zh/docs/dashboard-wire-out.md)
>
> 通过 Localpayment Business Portal 手动处理 Wire Out 指令，
> 提供可视化界面和分步指引。

***

## 步骤 1：通过 API 处理 Wire Out

要通过 API 发起 Wire Out 交易，请向 [Wire Out](https://docs.localpayment.com/zh/reference/wire-out.md) endpoint 发送 `POST` 请求。

### 关键请求参数

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

| 参数 | 描述 | 必需的 |
| - | - | - |
| `transactionType` | 必须设置为“WireOut” | ✅ |
| `externalId` | 您的交易唯一参考 ID | ✅ |
| `country` | 付款将处理至的 ISO 格式国家代码 | ✅ |
| `currency` | 交易金额的货币 | ✅ |
| `amount` | 将从您的账户扣除的金额 | ✅ |
| `accountNumber` | 您的Localpayment账号 | ✅ |
| `to` | 收款银行账户对象。**受益人必须是您本人**，即与源账户相同的账户持有人，而不是第三方。 | ✅ |
| `to.name` | 收款银行名称 | ✅ |
| `to.swift` | 收款银行的SWIFT/BIC代码 | ✅ |
| `to.address` | 收款银行地址 | ✅ |
| `to.accountName` | 收款银行的账户持有人姓名。 | ✅ |
| `to.accountNumber` | 收款银行账号。 | ✅ |
| `to.routingNumber` | 路由号码/排序代码（因国家/地区而异，例如，美国汇款） | ❌ |
| `to.beneficiaryAddress` | 您在收款银行的地址（作为受益人地址）。 | ✅ |
| `comment` | 关于交易的可选备注 | ❌ |

### 示例请求

> [tab] 标准（法币）
>
> ```bash curl theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
> curl --request POST \
>   --url https://api.stage.localpayment.com/api/account/wire-out \
>   --header 'Authorization: Bearer <your_access_token>' \
>   --header 'accept: application/json' \
>   --header 'content-type: application/json' \
>   --data '{
>     "transactionType": "WireOut",
>     "externalId": "c048aaea-5916-4dfe-add9-e3a720c42a08",
>     "country": "ARG",
>     "currency": "ARS",
>     "amount": 1000,
>     "accountNumber": "{{accountNumber}}",
>     "to": {
>       "name": "BBVA Arg.",
>       "swift": "BCSARG",
>       "address": "Centro 123",
>       "accountName": "John Doe",
>       "accountNumber": "3220001805117354710015",
>       "beneficiaryAddress": "Av. Corrientes 1234"
>     },
>     "comment": "Settlement"
>   }'
> ```

> [tab] 稳定币（USDC/USDT）
>
> ```bash curl theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
> curl --request POST \
>   --url https://api.stage.localpayment.com/api/account/wire-out \
>   --header 'Authorization: Bearer <your_access_token>' \
>   --header 'accept: application/json' \
>   --header 'content-type: application/json' \
>   --data '{
>     "transactionType": "WireOut",
>     "externalId": "a3f7c912-4e85-4b2d-9c0f-6d1e8a2b5f47",
>     "country": "GLO",
>     "currency": "USDC",
>     "amount": 100,
>     "accountNumber": "{{accountNumber}}",
>     "to": {
>       "name": "Banco Galicia",
>       "swift": "GALVARAR",
>       "address": "123 Blockchain Ave",
>       "accountName": "Jane Doe",
>       "accountNumber": "{{walletAddress}}",
>       "routingNumber": "routingNumber",
>       "beneficiaryAddress": "123 Blockchain Ave"
>     },
>     "comment": "Stablecoin settlement"
>   }'
> ```
>
> > [!NOTE]
> >
> > 对于稳定币 Wire Out，请将 `currency` 设置为 `"USDC"` 或 `"USDT"`。`country` 请使用 `"GLO"` 或与目标钱包对应的 ISO alpha-3 国家/地区代码。`to.accountNumber` 字段必须包含目标钱包地址。

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

***

## 步骤 2：处理响应

### 成功响应

成功发起的 Wire Out 会返回交易详情及初始状态：

> [tab] 标准（法币）
>
> ```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
> {
>     "transactionType": "WireOut",
>     "externalId": "c048aaea-5916-4dfe-add9-e3a720c42a08",
>     "internalId": "c0e5ec40-b5b6-49aa-8c2d-b1ba01080100",
>     "country": "ARG",
>     "currency": "ARS",
>     "clientCode": "0001",
>     "creationDate": "2025-09-29T18:41:49.940+00:00",
>     "errors": [],
>     "status": {
>         "code": "100",
>         "description": "RECEIVED",
>         "detail": "WIRE OUT"
>     },
>     "accountNumber": "{{accountNumber}}",
>     "amount": 1000.0,
>     "fees": {
>         "description": "Fee",
>         "currency": "ARS",
>         "amount": 30.0,
>         "account": "{{accountNumber}}"
>     },
>     "localTaxes": [],
>     "withHoldings": [],
>     "comment": "Settlement"
> }
> ```

> [tab] 稳定币（USDC/USDT）
>
> ```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
> {
>     "internalId": "53f2fcb7-0cf0-40f4-8416-2d00e91786a1",
>     "externalId": "a3f7c912-4e85-4b2d-9c0f-6d1e8a2b5f47",
>     "clientCode": "0001",
>     "country": "GLO",
>     "errors": [],
>     "accountNumber": "{{accountNumber}}",
>     "code": "102",
>     "comment": "Stablecoin settlement",
>     "creationDate": "2026-01-15T15:18:43.121+00:00",
>     "localTaxes": [],
>     "status": {
>         "code": "102",
>         "description": "Received",
>         "detail": "Authorized"
>     },
>     "transactionType": "WireOut",
>     "currency": "USDC",
>     "fees": {
>         "account": "{{accountNumber}}",
>         "amount": 0,
>         "currency": "USDC",
>         "description": "Fee"
>     },
>     "withHoldings": [],
>     "amount": 100,
>     "transactionFlow": "wireInAutomatic"
> }
> ```

### 关键响应字段

| 参数 | 描述 | 用例 |
| - | - | - |
| `externalId` | 您在原始交易中的参考编号。 | 对账和跟踪。 |
| `internalId` | Localpayment的唯一退款标识符。 | 用于支持和审计目的。 |
| `status.code` | 当前交易状态码。 | 状态监控。 |
| `creationDate` | 交易创建时。 | 审计追踪和报告。 |

### 错误响应

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

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
    "status": {
        "code": "300",
        "description": "REJECTED",
        "detail": "[to.address must not be empty]"
    },
    "timestamp": "2025-09-29 18:52:05.640378596",
    "errors": [
        {
            "code": "300",
            "detail": "to.address must not be empty"
        }
    ]
}
```

***

## 步骤 3：追踪 Wire Out 状态

发起 Wire Out 后，可通过以下方法监控其进度：

> [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)
>
> 用于监控交易的可视化界面。非常适合人工监督和详细的交易分析。

### 常见 Wire Out 状态代码

| 代码 | 状态 | 描述 |
| - | - | - |
| `100` | `PendingAuth` | 交易已创建，待授权 |
| `101` | `PendingDebit` | Localpayment验证后，交易正在处理中 |
| `102` | `Received` | 交易已授权 |
| `200` | `Completed` | 资金已成功转入收款银行 |
| `404` | `Rejected` | 提供商代码与账号不匹配 |
| `511` | `Rejected` | 请求中指定的金额为零 |
| `716` | `Rejected` | 授权过程中被管理员拒绝 |
| `717` | `RejectedByBank` | 交易被收款银行拒绝 |

> [!NOTE]
>
> **完成通知**
>
> 当交易达到 `Completed` 或 `Rejected` 状态时，您将收到电子邮件通知，无论交易是通过 API 还是 Business Portal 发起。对于加密货币 Wire Out 交易（USDC/USDT），`Completed` webhook 回调还会包含区块链交易哈希（`hash` 字段），以便您在区块浏览器中独立验证付款。此字段不适用于法币 Wire Out——完整的负载示例请参阅 [Webhooks](https://docs.localpayment.com/zh/docs/webhooks.md)。

***

## Business Portal Wire Out 处理

Wire Out 交易也可以通过 Localpayment Business Portal 界面进行处理。这种方法提供了可视化的资金转账管理工作流程，尤其适用于：

* 无需 API 自动化的一次性结算\*\*。
* 通过可视化授权工作流程进行管理监督\*\*。
* 无需开发资源即可进行**快速资金转账**。

有关通过 Business Portal 处理 Wire Out 交易的详细说明，包括分步指南和界面演示，请参阅[Business Portal Wire Out 指南](https://docs.localpayment.com/zh/docs/dashboard-wire-out.md)。

***

## 测试您的集成

### 测试场景

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

1. **成功的 Wire Out**：使用有效参数和充足余额处理转账。
2. **资金不足**：尝试转账金额超过账户余额。
3. **无效的银行信息**：请使用错误的 SWIFT 代码或账号进行测试。
4. **授权工作流程**：验证待审批授权状态和审批流程。

***

## 后续步骤

> [card] [查看交易状态](https://docs.localpayment.com/zh/reference/get-transaction-status.md)
>
> 使用交易状态 API 查看 Wire Out 交易的
> 当前状态。

> [card] [配置 Webhook](https://docs.localpayment.com/zh/docs/webhooks.md)
>
> 设置 Webhook 以接收 Wire Out 状态变更的
> 实时通知。


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