> ## 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 使您能够以最佳汇率和处理效率，通过编程方式执行单个或多个 外汇 (FX) 交易。

## 先决条件

创建货币兑换之前，请确保您已具备以下条件：

* **具有货币兑换权限的有效 API 凭证**。
* **需提供有效的汇款和收款货币账号**。
* **您的源货币账户中有足够的余额**。

> [!WARNING]
>
> **重要的**
>
> 您可以使用我们的[货币兑换报价 API](https://docs.localpayment.com/zh/docs/quote-currency-conversion.md)预先生成汇率报价，并在批量请求中包含 `exchangeRateToken` 以锁定汇率。

***

## API endpoint

要创建批量兑换，请向[创建批量外汇转换](https://docs.localpayment.com/zh/reference/exchange-bulk.md)endpoint 发送 `POST` 请求。

### endpoint

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

### 验证

在所有 API 请求中包含您的访问令牌：

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

### 关键请求参数

| 参数 | 类型 | 描述 |
| - | - | - |
| `externalId` | string | 您的交易唯一标识符 |
| `country` | string | ISO国家代码 |
| `currency` | string | 基础货币代码 |
| `account.debited` | object | 来源账户详情 |
| `account.credited` | object | 目标账户详情 |

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

```bash curl theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
curl --request POST \
     --url https://api.stage.localpayment.com/currency-exchange \
     --header 'Authorization: Bearer <your_access_token>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '{
       "country": "ARG",
       "currency": "ARS", 
       "externalId": "7a9c72a0-7a8e-4f72-b2b3-a04054d3129f",
       "account": {
         "debited": {
           "currency": "ARS",
           "accountNumber": "{{accountNumber}}", 
           "amount": 10000
         },
         "credited": {
           "currency": "EUR",
           "accountNumber": "{{accountNumber}}"
         }
       }
     }'
```

***

## 响应处理

### 成功响应

货币兑换成功后，系统会返回交易详情：

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "transactionType": "CurrencyExchange",
  "externalId": "7a9c72a0-7a8e-4f72-b2b3-a04054d3129f",
  "internalId": "8888ad65-aa6e-4643-b9ba-ff62318fd90b", 
  "country": "ARG",
  "currency": "ARS",
  "exchangeRateToken": "",
  "clientCode": "0005",
  "creationDate": "2023-03-21T21:25:14.533+00:00",
  "errors": [],
  "status": {
    "code": "200",
    "description": "COMPLETED",
    "detail": "CURRENCY EXCHANGE"
  },
  "account": {
    "debited": {
      "currency": "ARS", 
      "accountNumber": "{{accountNumber}}",
      "amount": 10000
    },
    "credited": {
      "currency": "EUR",
      "accountNumber": "{{accountNumber}}", 
      "amount": 44.52
    },
    "appliedFx": 224.54
  }
}
```

### 关键响应字段

| 字段 | 描述 |
| - | - |
| `internalId` | 系统生成的交易 ID 用于跟踪 |
| `status.code` | 当前交易状态代码 |
| `account.appliedFx` | 转换时采用的汇率 |
| `account.credited.amount` | 最终转换金额 |

***

### 错误响应

#### 资金不足

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "externalId": "7a9c72a0-7a8e-4f72-b2b3-a04054d3129f",
  "internalId": "6fc7e955-7704-4558-8a05-6f4a2c3d9b45",
  "errors": [
    {
      "code": "101",
      "detail": "Insufficient funds in source account"
    }
  ],
  "status": {
    "code": "101", 
    "description": "REJECTED",
    "detail": "Insufficient funds in source account"
  }
}
```

***

## 交易状态跟踪

通过多种渠道监控您的货币兑换情况：

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

### 状态生命周期

| 代码 | 状态 | 描述 |
| :- | :- | :- |
| `103` | `APPROVED` | 货币兑换已获批准 |
| `200` | `COMPLETED` | 货币兑换结束了。 |
| `303` | `REJECTED` | 此汇率代币已过期。 |
| | | |

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

***

## 高级功能

### 使用汇率报价

预先生成报价，锁定优惠利率：

1. **生成报价**：调用[货币兑换报价 API](https://docs.localpayment.com/zh/reference/currency-exchange-quote.md)
2. **获取令牌**：从响应中提取 `exchangeRateToken`
3. **应用代币**：在您的批量兑换请求中包含代币

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "exchangeRateToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "externalId": "7a9c72a0-7a8e-4f72-b2b3-a04054d3129f",
  "account": {
    // ... rest of request
  }
}
```

### 批量处理技巧

**性能优化**

* **批量请求**：尽可能将多个交易合并为单个 API 调用。
* **速率限制**：对高容量处理实施指数退避。
* **Webhook 处理**：使用 webhook 而不是轮询来获取状态更新。
* **错误重试逻辑**：针对临时故障实施智能重试机制。

***

## 测试与验证

### 沙盒环境

在我们的沙盒环境中测试您的集成：

```http theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
POST https://api.sandbox.localpayment.com/currency-exchange
```

### 测试场景

上线前请验证以下场景：

* 使用有效账户成功完成货币兑换
* 资金不足的错误处理
* 汇率代币到期
* 无效账号处理
* 网络超时场景
* 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.