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

# 收到汇款通知

使用我们的 API 向 Localpayment 通知一笔收到的电汇，以结算您的账户余额。本指南将引导您完成发起通知、处理 API 响应以及跟踪交易状态的全过程。

对于以法定货币（例如 USD、ARS、MXN）进行的交易，您需要通知我们收到汇款。您可以通过以下方式完成此操作：

* **[API集成](https://docs.localpayment.com/zh/reference/wire-in.md)**：推荐用于自动化、程序化通知。
* **[LocalpaymentBusiness Portal](https://docs.localpayment.com/zh/docs/dashboard-create-a-wire-in.md)**：使用网页界面手动通知个别交易。

> [!WARNING]
>
> **重要的**
>
> Wire In 通知流程不适用于 **稳定币**。请改为遵循[稳定币 Wire In 流程](https://docs.localpayment.com/zh/docs/wire-in-overview)。

本指南涵盖从通知到最终结算的完整 API 工作流程。

***

## 开始之前

在通知 Wire In 之前，请确保您已具备：

* **电汇凭证**：外部转账的证明。
* **有效的 API 凭据**：具有相应的授权权限。
* **完整的交易详情**：所有必需的交易信息。

***

## API endpoint

要通知结算，请向 [Create Wire In](https://docs.localpayment.com/reference/wire-in.md) endpoint 发送 `POST `请求。

### endpoint

```http theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
POST https://api.stage.localpayment.com/api/account/wire-in
```

### 验证

请在 Authorization 标头中包含您的访问令牌：

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

### 关键请求参数

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

| 参数 | 类型 | 说明 | 必需的 |
| - | - | - | - |
| `transactionType` | string | 必须设置为“WireIn” | ✅ |
| `currency` | string | 货币代码（例如“ARS”、“USD”） | ✅ |
| `country` | string | 国家代码（例如“ARG”、“USA”） | ✅ |
| `amount` | number | 转账金额 | ✅ |
| `accountNumber` | string | 您的Localpayment账号 | ✅ |
| `to` | object | 收款方银行详情 | ✅ |
| `from` | object | 汇款方银行详情 | ✅ |

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

```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-in \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer 123' \
  --header 'Content-Type: multipart/form-data' \
  --form 'request={\"transactionType\":\"WireIn\",\"currency\":\"BOB\",\"country\":\"BOL\",\"amount\":100,\"comment\":\"Comment\",\"externalId\":\"a11h7890-78ju-098j-hu78-124ftn8lo0io\",\"accountNumber\":\"{{accountNumber}}\",\"to\":{\"name\":\"Bankname\",\"swift\":\"BCBHDOSD\",\"address\":\"BankAddress\",\"accountNumber\":\"1310825187\",\"accountName\":\"BeneficiaryBankName\",\"beneficiaryAddress\":\"BeneficiaryAddress\"},\"from\":{\"name\":\"OrderingBankName\",\"swift\":\"BICAARBS\",\"address\":\"OrderingBankAddress\",\"accountNumber\":\"123456789\",\"routingNumber\":null,\"accountName\":\"accountName\",\"beneficiaryAddress\":\"BeneficiaryAddress\",\"intermediaryBankName\":null,\"intermediaryBankSwift\":null,\"intermediaryAccountNumer\":null}}' \
  --form filecontent=@CO.png
```

***

## 响应处理

### 成功响应

Wire In 请求被接受后，您将收到一条详细的响应：

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
    "transactionType": "WireIn",
    "transactionFlow": "wireInAutomatic",
    "externalId": "a11h7890-78ju-098j-hu78-124ftn8lo0io",
    "internalId": "b97fe1cd-50d3-4ee2-8a6e-34ee6d7e4f4e",
    "country": "BOL",
    "currency": "BOB",
    "clientCode": "0001",
    "creationDate": "2025-12-04T21:07:41.689+00:00",
    "errors": [],
    "status": {
        "code": "101",
        "description": "PENDING_AUTH",
        "detail": "Pending Auth"
    },
    "accountNumber": "{{accountNumber}}",
    "amount": 97.32,
    "fees": {
        "description": "Fee",
        "currency": "BOB",
        "amount": 0.5,
        "account": "{{accountNumber}}"
    },
    "localTaxes": [
        {
            "code": "0016",
            "percentage": 2.18,
            "description": "FNA",
            "currency": "BOB",
            "fxSource": 6.911493,
            "fxQuote": 0.0,
            "amount": 2.18,
            "account": "{{accountNumber}}"
        }
    ],
    "withHoldings": [],
    "comment": "Comment",
    "code": "101"
}
```

#### 关键响应字段

| 字段 | 类型 | 说明 |
| - | - | - |
| `externalId` | string | 您的唯一交易标识符 |
| `internalId` | string | Localpayment 的内部交易 ID |
| `creationDate` | string | 交易创建时间戳（ISO 8601） |
| `amount` | number | 扣除费用后的净额 |
| `fees` | object | 适用的处理费用 |
| `status` | object | 当前交易状态信息 |

### 错误响应

#### 验证错误示例

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "externalId": "089c81c6-7be2-4798-8e53-d4bfff61f852",
  "errors": [
    {
      "code": "404",
      "detail": "This beneficiary account is invalid"
    }
  ],
  "status": {
    "code": "404", 
    "description": "REJECTED",
    "detail": "This beneficiary account is invalid"
  }
}
```

***

## 跟踪交易状态

提交 Wire In 后，可通过以下方式监控其进度：

> [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` | `PendingCredit` | 待入账 |
| `200` | `Completed` | 已完成 |
| `717` | `RejectedByBank` | 已拒绝 |

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

### 安全建议

* API 请求务必使用 HTTPS
* 安全存储访问令牌（切勿存储在客户端代码中）
* 实施适当的错误处理和日志记录
* 在发送请求之前验证所有输入数据

***

## 资源与后续步骤

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

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