> ## Documentation Index > Fetch the complete documentation index at: https://developers.uqpay.com/llms.txt > Use this file to discover all available pages before exploring further. # Create Conversion > 在你的 UQPAY 账户余额内创建一笔新的换汇。这允许你以可用汇率将一种币种兑换为另一种币种。 ##### 使用说明 - 如果使用预生成的报价，请提供有效的 `quote_id`。关键的换汇参数（`buy_currency`、`sell_currency`、`conversion_date`）必须与报价详情一致。 - 同时指定 `buy_currency` 和 `sell_currency`，但 `buy_amount` 与 `sell_amount` 只定义其中之一。所定义的金额代表交易（固定）的一方，另一方金额将根据 UQPAY 的汇率自动计算。 ## OpenAPI ````yaml /zh/global-account/v1.6/banking.yaml post /v1/conversion openapi: 3.0.2 info: title: Banking API version: 0.0.1 x-source-en-commit: 5e7e320 x-source-en-path: global-account/v1.6/banking.yaml description: | UQPAY Banking API 为全球资金流转提供完整的银行与支付解决方案。 ## 核心功能 - 国际支付与转账 - 多币种账户管理 - 实时换汇 - 虚拟账户服务 - 资金充值与提现 ## 认证 调用 UQPAY API 时，使用 API 密钥对客户端请求进行认证。 API 密钥是用于认证用户身份、授予特权操作访问权限的唯一数据字符串。 请始终对 API 密钥保密并妥善保管。 ## 服务组件 - **Payout**：创建并管理向受益人发起的国际资金转账 - **Payer**：管理发起付款并授权资金转账的实体 - **Beneficiary**：管理收款方信息与银行信息 - **Balance**：查看并管理多币种账户余额 - **Deposit**：处理入账资金转账 - **Virtual Accounts**：使用外币本地银行账户 - **Conversion**：以有竞争力的汇率执行换汇 ## 快速开始 1. 获取 API 凭证 2. 使用 sandbox URL 搭建测试环境 3. 接入认证 4. 从基础操作开始 ## 支持 如需技术支持与集成协助，请联系 UQPAY 支持团队。 contact: name: UQPAY Support url: https://www.uqpay.com/support email: banking.tech@uqpay.com license: name: Proprietary url: https://www.uqpay.com/legal/api-terms termsOfService: https://www.uqpay.com/legal/terms x-api-id: banking-api-v1.6.0 x-logo: url: https://uqpay.com/img/UQPAY_LogoAnimv2.gif backgroundColor: '#FFFFFF' altText: UQPAY Logo x-categories: - Banking - Payment Processing - Foreign Exchange servers: - url: https://api-sandbox.uqpaytech.com/api description: Sandbox 基础 URL。 - url: https://api.uqpay.com/api description: 生产环境基础 URL。 security: [] tags: - name: Balances description: 查看并管理账户中不同币种的可用资金。 - name: Transfers description: 钱包转账资源用于将资金从你的 UQPAY 账户直接转入关联账户。 - name: Deposits description: 充值是指向你的 UQPAY 全球收款账户发起的银行转账，用于补充资金或从第三方收款。 - name: Virtual Accounts description: 虚拟账户是以外币形式存在的本地银行账户。它们支持全球收款，提供可从各类平台收款的账户信息。虚拟账户也可用于为 UQPAY 余额充值。 - name: Payout description: >- 当你向受益人发起付款时会创建一个 Payout 资源。它记录受益人、银行信息、付款金额、状态及其他相关信息。你可以使用直接填写的受益人信息，或使用先前创建的受益人 ID 来创建 payout。 - name: Payers description: 付款人是发起 payout 并授权将资金从其账户转入受益人账户的一方。 - name: Beneficiaries description: 受益人是资金的收款方，通常也是最终从 payout 中获益的一方。 - name: Conversion description: 管理交易的换汇与汇率。 - name: Exchange Rates description: 获取指定货币对或全部可用货币对的实时汇率。 - name: Global Accounts description: ⚠️ 警告 此 API 版本已弃用。已弃用的 API 版本最终将不再受支持。全球收款账户是充当本地银行账户的外币账户。 - name: Simulator description: 在 sandbox 环境中模拟充值交易。 paths: /v1/conversion: post: tags: - Conversion summary: Create Conversion description: > 在你的 UQPAY 账户余额内创建一笔新的换汇。这允许你以可用汇率将一种币种兑换为另一种币种。 ##### 使用说明 - 如果使用预生成的报价，请提供有效的 `quote_id`。关键的换汇参数（`buy_currency`、`sell_currency`、`conversion_date`）必须与报价详情一致。 - 同时指定 `buy_currency` 和 `sell_currency`，但 `buy_amount` 与 `sell_amount` 只定义其中之一。所定义的金额代表交易（固定）的一方，另一方金额将根据 UQPAY 的汇率自动计算。 operationId: create-conversion parameters: - $ref: '#/components/parameters/XOnBehalfOf' - $ref: '#/components/parameters/XIdempotencyKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateConversionRequest' responses: '200': description: OK —— 成功获取 payout。 headers: x-response-id: $ref: '#/components/headers/XResponseId' content: application/json: schema: $ref: '#/components/schemas/CreateConversionResponse' title: PayoutDetailResponse security: - XAuthToken: [] components: parameters: XOnBehalfOf: in: header name: x-on-behalf-of schema: type: string required: false description: > 指定代表哪个子账户发起请求。应设为 `account_id`，可通过[查询关联账户列表](/zh/account-center/v1.6/api-reference/list-connected-accounts-1)获取。如果省略或留空，请求将使用主账户执行。 更多信息参见[关联账户](/zh/account-center/v1.6/guide/connected-accounts)。 example: 18523f72-f4de-4f9c-bb8e-ec7d1c4f32be XIdempotencyKey: in: header name: x-idempotency-key schema: type: string format: uuid required: true description: 用于保持操作幂等性的唯一标识符（UUID），确保同一操作的重复执行不会产生意外影响或重复。它有助于在网络错误、重试或失败时保持数据一致性。 example: 2adesf8e-9d63-44bc-b975-9b6ae3440dde schemas: CreateConversionRequest: type: object required: - quote_id - buy_currency - sell_currency - conversion_date properties: quote_id: type: string example: 784832f7-1f8a-4b08-ac2a-8719b5b2a590 description: 报价的唯一 UUID 标识符。 sell_currency: type: string description: >- 币种代码 [ISO_4217](https://en.wikipedia.org/wiki/ISO_4217#List_of_ISO_4217_currency_codes)。 example: USD sell_amount: type: string example: '1000.00' description: 换汇中卖出币种的金额。 buy_currency: type: string description: >- 币种代码 [ISO_4217](https://en.wikipedia.org/wiki/ISO_4217#List_of_ISO_4217_currency_codes)。 example: SGD buy_amount: type: string example: '1000.00' description: 换汇中买入币种的金额。 conversion_date: type: string example: '2024-08-26' description: | 指定将执行换汇的日期。该日期必须是有效的可换汇日期。 仅支持当前日历日期 —— 不允许过去或未来的日期。 格式：`YYYY-MM-DD`。 CreateConversionResponse: type: object required: - conversion_id - short_reference_id - buy_amount - buy_currency - sell_amount - sell_currency - created_date - currency_pair - reference - status properties: conversion_id: type: string example: 784832f7-1f8a-4b08-ac2a-8719b5b2a590 description: 换汇交易的唯一 UUID 标识符。 short_reference_id: $ref: '#/components/schemas/ShortReferenceId' sell_currency: type: string description: >- 币种代码 [ISO_4217](https://en.wikipedia.org/wiki/ISO_4217#List_of_ISO_4217_currency_codes)。 example: USD sell_amount: type: string example: '10' description: 换汇中卖出币种的金额。 buy_currency: type: string description: >- 币种代码 [ISO_4217](https://en.wikipedia.org/wiki/ISO_4217#List_of_ISO_4217_currency_codes)。 example: SGD buy_amount: type: string example: '7.36' description: 换汇中买入币种的金额。 created_date: type: string example: '2024-08-22T17:12:58+08:00' description: 换汇交易发起时的时间戳。 currency_pair: type: string example: USDSGD description: 该报价对应的货币对。货币对的方向尽可能遵循市场惯例。 reference: type: string example: XC240822-TXCRW2EI description: 系统生成的用于标识该实体的编号。 status: type: string example: AWAITING_FUNDS description: | 该换汇交易的当前状态。有效值为： - `PROCESSING`：换汇请求正在由系统处理中。 - `AWAITING_FUNDS`：系统正在等待源资金到位。 - `TRADE_SETTLED`：已按约定汇率执行换汇。 - `FUNDS_ARRIVED`：已收到兑换后的目标币种资金。 ShortReferenceId: type: string example: P220406-LLCVLRM description: 系统生成的用于标识该实体的编号。 headers: XResponseId: description: 响应的通用唯一标识符（UUID v4）。在与 UQPAY 支持团队沟通时有助于定位某个请求。 schema: type: string format: uuid example: 2adba88e-9d63-44bc-b975-9b6ae3440dde securitySchemes: XAuthToken: type: apiKey in: header name: x-auth-token description: 由 UQPay 提供的登录 API Token。 ````