> ## 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，在同一国家内的您自有多币种账户之间高效兑换资金。这非常适合管理国际业务的企业优化其内部资金管理。

> **重要**
>
> * `account.debited.amount`：从源账户中扣除的金额。
> * `account.credited.amount`：划入目标账户的金额。
>   所提供字段的值必须大于 0。

> [!NOTE]
>
> **想在执行交易前锁定汇率吗？**
>
> 使用[货币兑换报价 API ](https://docs.localpayment.com/zh/reference/currency-exchange-quote.md)为该货币对生成汇率报价。响应中包含 `exchangeRateToken`，请在您的外汇转换请求中传入该令牌以锁定该汇率。报价汇率在该令牌的 `expirationDate` 之前始终有效，可保护您和您的用户免受市场波动的影响。


## OpenAPI

````yaml openapi/zh/localpayment.json POST /api/currency-exchange
openapi: 3.1.0
info:
  version: '1.0'
  title: Localpayment
  contact:
    name: Support
    url: mailto:support@localpayment.com
servers:
  - url: https://api.stage.localpayment.com
    description: Stage
security:
  - token: []
paths:
  /api/currency-exchange:
    post:
      summary: 创建批量外汇转换
      operationId: exchange-bulk
      parameters:
        - name: Authorization
          in: header
          description: >-
            用于身份验证的 Bearer
            访问令牌。该令牌可从[获取访问令牌](/zh/reference/get-token)或[刷新访问令牌](/zh/reference/refresh-token)endpoint
            获取。
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                country:
                  type: string
                  description: 处理该笔付款的国家/地区。
                externalId:
                  type: string
                  description: 系统生成的唯一标识符，用于跟踪交易（包含字母、数字和连字符）。我们建议使用 UUID4 以确保唯一性。
                exchangeRateToken:
                  type: string
                  description: 由外汇服务提供的令牌，用于使用预先约定的汇率
                account:
                  type: object
                  description: 包含交易账户详细信息的对象。
                  properties:
                    debited:
                      type: object
                      description: 待出账账户的详细信息。
                      properties:
                        currency:
                          type: string
                          description: 出账账户的币种。
                        accountNumber:
                          type: string
                          description: 将从中扣款的账号。
                        amount:
                          type: integer
                          description: >-
                            待扣款金额。如果 `account.credited.amount` 字段大于 0，则此参数必须设置为
                            0。
                      required:
                        - currency
                        - accountNumber
                        - amount
                    credited:
                      type: object
                      description: 待入账账户的详细信息。
                      properties:
                        currency:
                          type: string
                          description: 入账账户的币种。
                        accountNumber:
                          type: string
                          description: 资金将入账的账号。
                        amount:
                          type: integer
                          description: 待入账金额
                      required:
                        - currency
                        - accountNumber
                  required:
                    - debited
                    - credited
              required:
                - country
                - externalId
                - exchangeRateToken
                - account
              x-examples:
                Example 1:
                  country: ARG
                  currency: EUR
                  externalId: '11112222'
                  exchangeRateToken: ''
                  account:
                    debited:
                      currency: EUR
                      accountNumber: 111.1111.11111111
                      amount: 10
                    credited:
                      currency: USD
                      accountNumber: '{{accountNumber}}'
            examples:
              Without requesting a quote:
                value:
                  country: ARG
                  currency: ARS
                  externalId: 7a9c72a0-7a8e-4f72-b2b3-a04054d3129f
                  account:
                    debited:
                      currency: ARS
                      accountNumber: '{{accountNumber}}'
                      amount: 10000
                    credited:
                      currency: EUR
                      accountNumber: '{{accountNumber}}'
              With quote:
                value:
                  country: ARG
                  externalId: '11112222'
                  exchangeRateToken: af5606b0-1ce7-48f8-ad8a-734934c601ec
                  account:
                    debited:
                      currency: EUR
                      accountNumber: '{{accountNumber}}'
                      amount: 10
                    credited:
                      currency: USD
                      accountNumber: '{{accountNumber}}'
                      amount: 0
              Credited amount set:
                value:
                  country: ARG
                  externalId: '{{externalId}}'
                  exchangeRateToken: ''
                  account:
                    debited:
                      currency: ARS
                      accountNumber: 111.111.1111111
                      amount: 0
                    credited:
                      currency: USD
                      accountNumber: '{{accountNumber}}'
                      amount: 10
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  transactionType:
                    type: string
                    description: 交易类型。对于货币兑换操作，此值为 `CurrencyExchange`。
                  externalId:
                    type: string
                    description: 系统生成的唯一标识符，用于跟踪交易（包含字母、数字和连字符）。我们建议使用 UUID4 以确保唯一性。
                  internalId:
                    type: string
                    description: Localpayment交易标识符。
                  country:
                    type: string
                    description: 处理交易的国家/地区。
                  currency:
                    type: string
                    description: 交易的原始货币。
                  exchangeRateToken:
                    type: string
                    description: 用于跟踪该交易汇率的唯一标识符。
                  clientCode:
                    type: string
                    description: 在 LocalPayment 系统中分配给客户的唯一标识符。
                  creationDate:
                    type: string
                    description: 交易创建的日期和时间。
                  errors:
                    type: array
                    description: 如果在交易过程中发生任何错误，则返回一个错误对象数组。
                    items:
                      type: object
                  status:
                    type: object
                    properties:
                      code:
                        type: string
                        description: 表示交易当前状态的代码。
                      description:
                        type: string
                        description: 简要描述交易状态。
                      detail:
                        type: string
                        description: 有关交易状态的更多详细信息。
                  account:
                    type: object
                    properties:
                      debited:
                        type: object
                        properties:
                          currency:
                            type: string
                            description: 出账账户的货币。
                          accountNumber:
                            type: string
                            description: 出账账户的账号。
                          amount:
                            type: number
                            description: 从账户中扣除的金额。
                      credited:
                        type: object
                        properties:
                          currency:
                            type: string
                            description: 入账账户的货币。
                          accountNumber:
                            type: string
                            description: 入账账户的账号。
                          amount:
                            type: number
                            description: 记入账户的金额。
                      appliedFx:
                        type: number
                        description: 适用于该交易的外汇汇率。
                x-examples:
                  Example 1:
                    transactionType: CurrencyExchange
                    externalId: ''
                    internalId: X11111XX-11X1-111X-X11X-111111X1X1XX
                    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: 40
                      credited:
                        currency: EUR
                        accountNumber: '{{accountNumber}}'
                        amount: 0.18
                      appliedFx: 224.54
              examples:
                200 - Currency Exchange Bulk:
                  value:
                    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
        '400':
          description: 错误的请求
          content:
            application/json:
              schema:
                type: object
                properties:
                  externalId:
                    type: string
                    description: 系统生成的唯一标识符，用于跟踪交易（包含字母、数字和连字符）。我们建议使用 UUID4 以确保唯一性。
                  internalId:
                    type: string
                    description: Localpayment交易标识符。
                  errors:
                    type: array
                    description: 如果在交易过程中发生任何错误，则返回一个错误对象数组。
                    items:
                      type: object
                      properties:
                        code:
                          type: string
                          description: 错误代码。
                        detail:
                          type: string
                          description: 错误详情。
                  status:
                    type: object
                    properties:
                      code:
                        type: string
                        description: 表示交易当前状态的代码。
                      description:
                        type: string
                        description: 简要描述交易状态。
                      detail:
                        type: string
                        description: |
                          有关交易状态的更多详细信息。
                x-examples:
                  Example 1:
                    externalId: '11112222'
                    internalId: 6fc7e955-7704-4558-8a05-6f4a2c3d9b45
                    errors:
                      - code: '705'
                        detail: Credited account currency not match
                    status:
                      code: '705'
                      description: REJECTED
                      detail: Credited account currency not match
              examples:
                705 - Credited account currency not match:
                  value:
                    externalId: '11112222'
                    internalId: 6fc7e955-7704-4558-8a05-6f4a2c3d9b45
                    errors:
                      - code: '705'
                        detail: Credited account currency not match
                    status:
                      code: '705'
                      description: REJECTED
                      detail: Credited account currency not match
                707 - Debited and credited amounts are mutually exclusive:
                  value:
                    errors:
                      - code: '707'
                        detail: >-
                          Fields debited.amount and credited.amount are mutually
                          exclusive. Only one of them must be reported
                    status:
                      code: '707'
                      description: REJECTED
                      detail: >-
                        Fields debited.amount and credited.amount are mutually
                        exclusive. Only one of them must be reported
        '401':
          description: 未经授权
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                    description: 回复的补充信息。
                  code:
                    type: string
                    description: 状态码。
                  messages:
                    type: array
                    description: 消息列表。
                    items:
                      type: object
                      properties:
                        token_class:
                          type: string
                          description: Token 类。
                        token_type:
                          type: string
                          description: 令牌类型。
                        message:
                          type: string
                          description: 包含补充信息的消息。
                x-examples:
                  Example 1:
                    detail: Given token not valid for any token type
                    code: token_not_valid
                    messages:
                      - token_class: AccessToken
                        token_type: access
                        message: Token is invalid or expired
              examples:
                401 - Token is invalid or expired:
                  value:
                    detail: Given token not valid for any token type
                    code: token_not_valid
                    messages:
                      - token_class: AccessToken
                        token_type: access
                        message: Token is invalid or expired
      security:
        - token: []
      servers:
        - url: https://api.stage.localpayment.com
          description: Stage
components:
  securitySchemes:
    token:
      type: http
      scheme: bearer

````

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