> ## 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 凭据**
* 位于不同国家/地区的来源账户和目标账户均已完成**多国账户验证**

> [!WARNING]
>
> **重要**
>
> 两个账户必须以同一种货币注册。

***

## API 集成

要创建内部跨境转账，请向[创建内部转账](https://docs.localpayment.com/zh/reference/domestic-transfer.md)endpoint 发送 `POST` 请求。

### endpoint

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

### 验证

所有请求都需要安全的 bearer 令牌验证：

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

### 关键请求参数

| 参数 | 类型 | 描述 |
| - | - | - |
| `externalId` | string | 您用于跟踪的唯一交易标识符 |
| `country` | string | 来源账户的 ISO alpha-3 国家代码 |
| `currency` | string | 来源账户的 ISO 货币代码 |
| `amount` | number | 转账金额 |
| `transactionType` | string | 必须为 "InternalForeignTransfer" |
| `client.from.accountNumber` | string | 来源账号 |
| `client.to.accountNumber` | string | 目标账号（不同国家/地区） |

### 请求示例

```bash curl theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
curl --request POST \
     --url https://api.stage.localpayment.com/api/internal-transfer \
     --header 'Authorization: Bearer your_access_token' \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json' \
     --data '{
  "externalId": "IFT-2024-033214-05",
  "country": "ARG",
  "currency": "USD",
  "amount": 100.00,
  "transactionType": "InternalForeignTransfer",
  "client": {
    "type": "Client",
    "from": {
      "accountNumber": "{{accountNumber}}"
    },
    "to": {
      "accountNumber": "{{accountNumber}}"
    }
  }
}'
```

***

## 响应处理

我们的 API 提供全面的响应数据，以便有效地管理交易和进行对账。

### 转账成功响应

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "transactionType": "InternalForeignTransfer",
  "externalId": "IFT-2024-033214-05",
  "internalId": "a70614fe-b76c-4f6c-9a5a-7144f2f7ea1f",
  "country": "ARG",
  "currency": "USD",
  "clientCode": "0001",
  "creationDate": "2024-03-23T00:38:30.828+00:00",
  "errors": [],
  "status": {
    "code": "200",
    "description": "COMPLETED",
    "detail": "INTERNAL FOREIGN TRANSFER PROCESSED"
  },
  "amount": 100.00,
  "client": {
    "type": "Client",
    "from": {
      "accountNumber": "{{accountNumber}}"
    },
    "to": {
      "accountNumber": "{{accountNumber}}",
      "amount": 95.80
    }
  },
  "fees": {
    "description": "Cross-border transfer fee",
    "currency": "USD",
    "amount": 3.00,
    "account": "{{accountNumber}}"
  },
  "localTaxes": [
    {
      "code": "0001",
      "percentage": 1.2,
      "description": "International Debit Tax (IDC)",
      "currency": "USD",
      "amount": 1.20,
      "account": "{{accountNumber}}"
    }
  ],
  "withHoldings": []
}
```

#### 关键响应字段

| 字段 | 目的 |
| - | - |
| `internalId` | 系统生成的用于交易跟踪和支持的 UUID |
| `status.code` | 交易结果：200（SUCCESS）或 702+（ERROR） |
| `client.to.amount` | 扣除费用和税费后记入的净金额 |
| `fees.amount` | 向来源账户收取的处理费用总额 |
| `localTaxes` | 适用的司法管辖区税费的详细明细 |
| `creationDate` | 用于精确记录交易时间的 UTC 时间戳 |

### 错误响应处理

稳健的错误处理，并提供详细的诊断信息：

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "externalId": "IFT-ERROR-123",
  "internalId": "fc2c831c-d0f1-41f6-8a59-0ecd426c087d",
  "errors": [
    {
      "code": "702",
      "detail": "Source account not configured for international transfers"
    },
    {
      "code": "703", 
      "detail": "Cross-border transfer requires different country accounts"
    },
    {
      "code": "704",
      "detail": "Insufficient funds: Available balance inadequate for transfer + fees"
    }
  ],
  "status": {
    "code": "702",
    "description": "REJECTED",
    "detail": "Pre-transfer validation failed"
  }
}
```

***

## 交易状态跟踪

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

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

> [card] [状态 API](https://docs.localpayment.com/zh/docs/reporting-and-reconciliation.md)
>
> 使用交易 ID 以编程方式查询交易状态。非常适合状态轮询。

> [card] [Business Portal](https://docs.localpayment.com/zh/docs/dashboard-overview.md)
>
> 提供详细交易历史和分析的可视化监控界面。

### 状态生命周期

| 代码 | 状态 | 描述 |
| :- | :- | :- |
| `100` | `InProgress` | 进行中 |
| `102` | `PendingDebit` | 待借记 |
| `103` | `PendingCredit` | 待贷记 |
| `200` | `Completed` | 内部转账 |
| `704` | `Rejected` | 入账账户不存在 |

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

***

## 资源与后续步骤

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

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