> ## Documentation Index > Fetch the complete documentation index at: https://developers-sandbox.uqpaytech.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Create Virtual Account > 针对一个国家和一个币种申请虚拟账户银行信息。可以选择 `LOCAL` 或 `SWIFT`，也可以省略 `payment_method`，分别评估两种收款方式。 HTTP `200` 表示申请已受理并进入异步处理。请保存 `application_id` 和 `public_version`，逐项处理结果，并且只使用状态为 `ACTIVE` 的银行信息。 同步错误表示没有创建申请，后续也不会产生申请 Webhook。 支持的参数组合、状态处理、错误及可用性规则详见[通过 API 集成虚拟账户](/zh/global-account/v1.6/guide/virtual-account-api-lifecycle)。 ## OpenAPI ````yaml /zh/global-account/v1.6/banking.yaml post /v1/virtual/accounts openapi: 3.0.2 info: title: Banking API version: 0.0.1 x-source-en-commit: e67a603 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: Beneficiaries description: 受益人是资金的收款方，通常也是最终从 payout 中获益的一方。 - name: Conversion description: 管理交易的换汇与汇率。 - name: Exchange Rates description: 获取指定货币对或全部可用货币对的实时汇率。 - name: Global Accounts description: ⚠️ 警告 此 API 版本已弃用。已弃用的 API 版本最终将不再受支持。全球收款账户是充当本地银行账户的外币账户。 - name: Simulator description: 在 sandbox 环境中模拟充值交易。 paths: /v1/virtual/accounts: post: tags: - Virtual Accounts summary: Create Virtual Account description: > 针对一个国家和一个币种申请虚拟账户银行信息。可以选择 `LOCAL` 或 `SWIFT`，也可以省略 `payment_method`，分别评估两种收款方式。 HTTP `200` 表示申请已受理并进入异步处理。请保存 `application_id` 和 `public_version`，逐项处理结果，并且只使用状态为 `ACTIVE` 的银行信息。 同步错误表示没有创建申请，后续也不会产生申请 Webhook。 支持的参数组合、状态处理、错误及可用性规则详见[通过 API 集成虚拟账户](/zh/global-account/v1.6/guide/virtual-account-api-lifecycle)。 operationId: create-virtual-account parameters: - $ref: '#/components/parameters/XOnBehalfOf' - $ref: '#/components/parameters/VirtualAccountIdempotencyKey' requestBody: required: true content: application/json: schema: type: object required: - country - currency properties: country: type: string enum: - SG - DK - GB - DE - AU - LU - BH description: 虚拟账户开户国家的两位国家代码。请使用接入指南列出的组合。系统会去除首尾空格，并接受小写输入。 currency: type: string enum: - SGD - USD - AUD - CNH - EUR - GBP - HKD - JPY - NOK - AED - NZD - CHF - CAD - KWD - MXN description: 虚拟账户需要接收的三位币种代码。每次只能传一个值。系统会去除首尾空格，并接受小写输入。 payment_method: type: string nullable: true enum: - LOCAL - SWIFT - '' description: >- 要评估的收款方式。传 `LOCAL` 或 `SWIFT` 时只评估一种；省略，或传 `null`、空字符串、仅空白字符时，分别评估两种方式。不要传 `ALL` 或 `AUTO`。 nickname: type: string nullable: true maxLength: 255 description: >- 用于标记请求的可选名称。省略、为 `null`、为空或仅包含空白字符时按相同方式处理。申请接口和 Webhook 均不返回该值。 example: Operating account examples: explicitSwift: summary: 申请一个 SWIFT 虚拟账户 value: country: BH currency: GBP payment_method: SWIFT nickname: GBP collection account evaluateBothMethods: summary: 分别评估 LOCAL 和 SWIFT value: country: SG currency: USD responses: '200': headers: x-response-id: $ref: '#/components/headers/XResponseId' description: OK —— 虚拟账户申请已受理并进入异步处理。 content: application/json: schema: $ref: '#/components/schemas/VirtualAccountApplicationResponse' title: CreateVirtualAccountApplicationResponse examples: explicitMethod: summary: 一种收款方式已受理 value: data: account_id: b1b89684-c2c4-4d54-b8a8-3572727fd120 application_id: 550e8400-e29b-41d4-a716-446655440001 country: BH currency: EUR direct_id: '0' public_version: 1 status: SUBMITTED results: - payment_method: SWIFT status: SUBMITTED virtual_accounts: [] error: null omittedMethodPartialAcceptance: summary: 省略 payment_method 时分别评估两种方式 value: data: account_id: b1b89684-c2c4-4d54-b8a8-3572727fd120 application_id: 550e8400-e29b-41d4-a716-446655440000 country: SG currency: USD direct_id: '0' public_version: 1 status: SUBMITTED results: - payment_method: LOCAL status: SKIPPED virtual_accounts: [] error: code: VA_METHOD_NOT_SUPPORTED message: >- LOCAL is not supported for the requested country and currency - payment_method: SWIFT status: SUBMITTED virtual_accounts: [] error: null '400': description: >- Bad Request —— 申请未被受理，也未创建。Create 的参数校验和业务错误响应只包含 `type`、`code` 和 `message`，不包含 `results` 或 `details`。 headers: x-response-id: $ref: '#/components/headers/XResponseId' content: application/json: schema: $ref: '#/components/schemas/VirtualAccountApplicationErrorResponse' title: CreateVirtualAccountApplicationError examples: invalidCountry: summary: 国家代码无效 value: type: invalid_request_error code: invalid_parameter message: country must be a valid ISO-2 code allMethodsUnsupported: summary: 所有已评估方式的拒绝原因相同 value: type: account_error code: virtual_account_payment_method_not_supported message: >- None of the requested payment methods is supported for the specified country and currency 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 VirtualAccountIdempotencyKey: in: header name: x-idempotency-key schema: type: string maxLength: 64 required: true description: 本次申请的唯一键。仅在为同一账户重试相同请求时复用该键。输入规范化后，使用同一键提交不同的请求数据会返回错误。 example: 2adesf8e-9d63-44bc-b975-9b6ae3440dde headers: XResponseId: description: 响应的通用唯一标识符（UUID v4）。在与 UQPAY 支持团队沟通时有助于定位某个请求。 schema: type: string format: uuid example: 2adba88e-9d63-44bc-b975-9b6ae3440dde schemas: VirtualAccountApplicationResponse: type: object additionalProperties: false required: - data properties: data: $ref: '#/components/schemas/VirtualAccountApplication' VirtualAccountApplicationErrorResponse: type: object additionalProperties: false required: - type - code - message properties: type: type: string description: 用于分类和日志记录的错误大类。 example: invalid_request_error code: type: string description: 用于程序处理的稳定错误标识符。 example: invalid_parameter message: type: string description: 供排查问题使用的可读说明。不要将该文本作为程序判断标识符。 example: country must be a valid ISO-2 code VirtualAccountApplication: type: object additionalProperties: false required: - account_id - application_id - country - currency - direct_id - public_version - results - status properties: account_id: type: string format: uuid description: 申请所属账户。使用 `x-on-behalf-of` 时表示该关联账户；否则表示主账户。 example: b1b89684-c2c4-4d54-b8a8-3572727fd120 application_id: type: string format: uuid description: 这笔申请的标识符。Create 成功后请保存该值，用于查询详情和关联 Webhook 事件。 example: 550e8400-e29b-41d4-a716-446655440001 country: type: string description: Create 请求中提交的两位国家代码。每条已开通银行信息还会返回自己的 `country_code`。 example: BH currency: type: string description: Create 请求中提交的三位币种代码。 example: EUR direct_id: type: string description: 表示 `account_id` 的主账户关系。当 `account_id` 是主账户时为 `"0"`；否则为对应主账户 ID。 example: '0' public_version: type: integer format: int64 minimum: 1 description: 返回的申请数据版本。初始值为 `1`，返回数据变化时递增。对于同一 `application_id`，保留版本号最高的响应或事件。 example: 1 status: type: string enum: - SUBMITTED - PARTIALLY_COMPLETED - COMPLETED - FAILED - CLOSED description: 这笔申请的整体状态。该字段用于跟踪申请；判断银行信息是否可用前，仍需检查每个结果和银行信息的状态。各状态含义详见接入指南。 example: SUBMITTED results: type: array minItems: 1 maxItems: 2 description: >- 每种已评估收款方式对应一项结果。请逐项处理并通过 `payment_method` 识别。两种方式同时存在时，`LOCAL` 排在 `SWIFT` 之前。 items: $ref: '#/components/schemas/VirtualAccountApplicationResult' VirtualAccountApplicationResult: type: object additionalProperties: false required: - payment_method - status - virtual_accounts - error properties: payment_method: type: string enum: - LOCAL - SWIFT description: 这项结果对应的收款方式。`LOCAL` 使用受支持的本地清算网络；`SWIFT` 使用 SWIFT 网络。 example: SWIFT status: type: string enum: - SUBMITTED - COMPLETED - FAILED - SKIPPED - CLOSED description: >- 这项收款方式的状态。只有当该值为 `COMPLETED` 且具体银行信息状态为 `ACTIVE` 时，才能使用相应银行信息。各状态的处理方式详见接入指南。 example: SUBMITTED virtual_accounts: type: array description: 这项收款方式下已开通的银行信息。空数组表示该结果下没有已开通信息。只能使用 `status` 为 `ACTIVE` 的记录。 items: $ref: '#/components/schemas/VirtualAccountApplicationBankDetail' error: type: object nullable: true additionalProperties: false required: - code - message description: 这项收款方式被跳过或失败时的错误；没有错误时为 `null`。程序处理应使用 `code`。 properties: code: type: string description: 用于程序处理的稳定错误代码。支持的代码和建议操作详见接入指南。 example: VA_METHOD_NOT_SUPPORTED message: type: string description: 供排查问题使用的可读说明。不要将该文本用作程序判断依据。 example: LOCAL is not supported for the requested country and currency VirtualAccountApplicationBankDetail: type: object additionalProperties: false required: - account_bank_id - account_holder - account_number - country_code - currency - bank_name - bank_address - clearing_system - status - close_reason properties: account_bank_id: type: string description: 这条银行信息的稳定标识符。请将其视为不透明字符串并按原值保存，用于关联后续变化。 example: va-bank-detail-001 account_holder: type: string description: 向付款人展示的账户持有人名称，应按返回值原样使用。 example: John Doe account_number: type: string description: 付款人转账时必须使用的账号或 IBAN。请保留格式和前导零。 example: '12345678' country_code: type: string description: 此已开通银行账户的两位国家代码。生成付款指引时使用该返回值，不要仅根据 application 推断。 example: SG currency: type: string description: 此银行信息可以接收的三位币种代码。应要求付款人仅发送该币种。 example: USD bank_name: type: string description: 付款指引中应包含的银行名称。 example: ABC Bank bank_address: type: string description: 付款人银行或转账表单要求时应填写的银行地址。 example: 810 Seventh Avenue, New York, NY 10019, US clearing_system: type: object additionalProperties: false required: - type - value description: 此银行信息所需的路由标识。`type` 和 `value` 必须配套使用，并按返回值原样保留。 properties: type: type: string description: 路由标识的格式或网络，例如 `bic_swift`。 example: bic_swift value: type: string description: 与 `type` 对应的路由标识值，例如 BIC/SWIFT 代码或本地清算代码。 example: TCCLGB3L status: type: string enum: - ACTIVE - CLOSED description: 该银行信息是否可用。`ACTIVE` 可用于新的付款指引；`CLOSED` 不得继续展示或使用。 example: ACTIVE close_reason: type: string example: '' description: >- 始终存在的 string 字段。除 `status = CLOSED` 外始终为 `""`。记录关闭后，如系统已记录关闭原因则返回该值，否则仍为 `""`。请使用 `status` 判断银行信息是否已关闭，不要依赖该字段。 securitySchemes: XAuthToken: type: apiKey in: header name: x-auth-token description: 由 UQPAY 提供的登录 API Token。 ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.