> ## 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 Payout > 向受益人创建一笔新的 payout。依托 SWIFT 与本地支付通道的能力支持，你可以更快、更具成本效益地向海外企业账户、供应商和员工发起国际付款。 此 API 支持多种付款模式，包括标准 payout 和代付（POBO），实现灵活高效的资金管理。此外，你还可以选择费用承担方式，以控制交易手续费的处理方式。 #### 使用说明 - 支持以 30+ 种币种向 180 多个国家/地区发起 payout，包括向中国大陆发起的 CNY payout。 - 用于 POBO 交易的子账户必须提前创建，且账户状态必须为已激活。 - 要启用 POBO 模式，请在请求头中加入 `x-on-behalf-of` 参数，并指定用于该 payout 的子账户 ID。受益人将看到自定义的付款人名称，而非实际付款实体。 - 用户可通过 `fee_paid_by` 参数选择费用承担类型，以确定由谁承担交易费用： 1. `SHARED` —— 交易手续费由付款人与收款方分担；付款人承担汇出行费用，收款方承担收款行费用。 2. `OURS` —— 所有交易手续费（含中间行费用）均由付款人承担。 - 有两种方式指定受益人： 1. 使用 `beneficiary_id` —— 如果受益人已创建，提供 `beneficiary_id` 以引用现有受益人。 2. 提供完整的受益人信息 —— 如果受益人此前未创建，在请求中包含完整的受益人信息。此时不要传入 `beneficiary_id`。 **注意**：提供完整信息时会创建一个受益人。后续向同一受益人发起的任何 payout，都应传入对应的 `beneficiary_id`，而非完整的受益人信息。 - 如果你打算发起跨币种 payout，可参阅[跨币种指南](/zh/global-account/v1.6/guide/cross-currency-payout-guide)了解详情与示例。 ## OpenAPI ````yaml /zh/global-account/v1.6/banking.yaml post /v1/payouts 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/payouts: post: tags: - Payouts summary: Create Payout description: > 向受益人创建一笔新的 payout。依托 SWIFT 与本地支付通道的能力支持，你可以更快、更具成本效益地向海外企业账户、供应商和员工发起国际付款。 此 API 支持多种付款模式，包括标准 payout 和代付（POBO），实现灵活高效的资金管理。此外，你还可以选择费用承担方式，以控制交易手续费的处理方式。 #### 使用说明 - 支持以 30+ 种币种向 180 多个国家/地区发起 payout，包括向中国大陆发起的 CNY payout。 - 用于 POBO 交易的子账户必须提前创建，且账户状态必须为已激活。 - 要启用 POBO 模式，请在请求头中加入 `x-on-behalf-of` 参数，并指定用于该 payout 的子账户 ID。受益人将看到自定义的付款人名称，而非实际付款实体。 - 用户可通过 `fee_paid_by` 参数选择费用承担类型，以确定由谁承担交易费用： 1. `SHARED` —— 交易手续费由付款人与收款方分担；付款人承担汇出行费用，收款方承担收款行费用。 2. `OURS` —— 所有交易手续费（含中间行费用）均由付款人承担。 - 有两种方式指定受益人： 1. 使用 `beneficiary_id` —— 如果受益人已创建，提供 `beneficiary_id` 以引用现有受益人。 2. 提供完整的受益人信息 —— 如果受益人此前未创建，在请求中包含完整的受益人信息。此时不要传入 `beneficiary_id`。 **注意**：提供完整信息时会创建一个受益人。后续向同一受益人发起的任何 payout，都应传入对应的 `beneficiary_id`，而非完整的受益人信息。 - 如果你打算发起跨币种 payout，可参阅[跨币种指南](/zh/global-account/v1.6/guide/cross-currency-payout-guide)了解详情与示例。 operationId: create-payout parameters: - in: header name: x-on-behalf-of schema: type: string required: false description: >- 设为关联账户的 ID。若该值非空，请求参数 `is_payer` 将默认为 `Y`。更多信息参见[查询关联账户列表](/zh/account-center/v1.6/api-reference/list-connected-accounts) example: 18523f72-f4de-4f9c-bb8e-ec7d1c4f32be - $ref: '#/components/parameters/XIdempotencyKey' requestBody: content: application/json: schema: $ref: '#/components/schemas/PayoutCreationRequest' responses: '200': headers: x-response-id: $ref: '#/components/headers/XResponseId' description: Payout 创建成功。 content: application/json: schema: $ref: '#/components/schemas/PayoutCreationResponse' title: PayoutCreationResponse security: - XAuthToken: [] components: parameters: XIdempotencyKey: in: header name: x-idempotency-key schema: type: string format: uuid required: true description: 用于保持操作幂等性的唯一标识符（UUID），确保同一操作的重复执行不会产生意外影响或重复。它有助于在网络错误、重试或失败时保持数据一致性。 example: 2adesf8e-9d63-44bc-b975-9b6ae3440dde schemas: PayoutCreationRequest: type: object required: - currency - amount - purpose_code - payout_reference - fee_paid_by - payout_date properties: currency: $ref: '#/components/schemas/SourceCurrency' amount: $ref: '#/components/schemas/Amount' quote_id: type: string example: 784832f7-1f8a-4b08-ac2a-8719b5b2a590 description: > 预先创建的报价的 ID，通过[创建报价](/zh/global-account/v1.6/api-reference/create-quote)获取。 仅在跨币种 payout 场景下需要。 如果提供，还必须同时提供 `payout_currency` 和 `payout_amount`。 payout_currency: type: string description: > 受益人将收到的币种。完整的可用币种列表请参阅[支持的币种](/zh/global-account/v1.6/guide/cross-currency-payout-supported-currency-pairs)。 当指定 `quote_id` 时必填。必须与创建报价响应中返回的 `buy_currency` 一致。 example: SGD payout_amount: type: number format: decimal description: | 受益人将收到的金额，以 `payout_currency` 计。 当指定 `quote_id` 时必填。必须与创建报价响应中返回的 `buy_amount` 一致。 example: 100 purpose_code: $ref: '#/components/schemas/PurposeCode' payout_reference: $ref: '#/components/schemas/PayoutReference' fee_paid_by: $ref: '#/components/schemas/FeePaidBy' payout_date: $ref: '#/components/schemas/PayoutDate' beneficiary_id: type: string format: uuid example: b3d9d2d5-4c12-4946-a09d-953e82sed2b0 description: >- 受益人的通用唯一标识符（UUID v4）。可用它替代 beneficiary 部分；如果已提供 beneficiary 各字段，则此项应留空，反之亦然。 beneficiary: $ref: '#/components/schemas/BeneficiaryCreationRequest' description: payout 请求中受益人的信息。如果 payout 请求中提供了 beneficiary_id，则 beneficiary 应留空。 is_payer: $ref: '#/components/schemas/IsPayer' payer_id: $ref: '#/components/schemas/CreationPayerId' documentation: type: array description: > 与该 payout 相关的证明文件。 - **一般情况**：可选字段，用于附加与该 payout 相关的文件。 - **必填情况**：当 `beneficiary.bank_details.account_currency_code = INR` 且 `clearing_system = IFSC` 时，必须通过 `documentation` 字段上传**发票文件**。 items: $ref: '#/components/schemas/PayoutDocumentationItem' type: object PayoutCreationResponse: type: object properties: payout_id: $ref: '#/components/schemas/PayoutId' short_reference_id: $ref: '#/components/schemas/ShortReferenceId' payout_status: $ref: '#/components/schemas/PayoutStatus' SourceCurrency: type: string example: USD description: | 付款人将汇出的币种。 maxLength: 3 minLength: 3 Amount: type: string example: '1000.00' description: | 付款人将汇出的金额，以 `currency` 计。 PurposeCode: type: string example: AUDIO_VISUAL_SERVICES description: | payout 的用途代码，必须为以下之一： * `AUDIO_VISUAL_SERVICES` - 视听服务。 * `BILL_PAYMENT` - 账单支付。 * `BUSINESS_EXPENSES` - 企业开支。 * `CONSTRUCTION` - 建筑。 * `DONATION_CHARITABLE_CONTRIBUTION` - 捐赠/慈善捐赠。 * `EDUCATION_TRAINING` - 教育/培训。 * `FAMILY_SUPPORT` - 家庭赡养。 * `FREIGHT` - 运费。 * `GOODS_PURCHASED` - 购买商品。 * `INVESTMENT_CAPITAL` - 投资本金。 * `INVESTMENT_PROCEEDS` - 投资收益。 * `LIVING_EXPENSES` - 生活开支。 * `LOAN_CREDIT_REPAYMENT` - 贷款/信贷还款。 * `MEDICAL_SERVICES` - 医疗服务。 * `PENSION` - 养老金。 * `PERSONAL_REMITTANCE` - 个人汇款。 * `PROFESSIONAL_BUSINESS_SERVICES` - 专业/商业服务。 * `REAL_ESTATE` - 房地产。 * `TAXES` - 税费。 * `TECHNICAL_SERVICES` - 技术服务。 * `TRANSFER_TO_OWN_ACCOUNT` - 转账至本人账户。 * `TRAVEL` - 旅行。 * `WAGES_SALARY` - 工资/薪酬。 PayoutReference: type: string maxLength: 100 example: '026073150' description: > 显示在受益人银行交易记录中的银行付款附言。会发送给收款方（如 For Further Credit、For Benefit of 或自定义信息）。在控制台中亦称 Payment reference。 - **SWIFT 付款**：必须符合正则 `/^[a-zA-Z0-9/-?:().'+, ]+$/`。 允许的字符：英文字母、数字、空格，以及以下特殊符号：`- / ? : ( ) . ' + ,`。 - **LOCAL 付款**：当 `payment_method = LOCAL` 且 `account_currency_code` 不是 CNH 或 SGD 时，不应用输入格式校验。 FeePaidBy: type: string example: SHARED description: > 付款手续费的承担类型。仅在 `payment_method = SWIFT` 时生效并必填。 - `SHARED`：交易手续费由付款人与收款方分担；付款人承担汇出行费用，收款方承担收款行费用。当付款人为企业且付款人所在国家/地区为 SG、VN、HK 或 AU 之一时，SWIFT payout 可使用此项。 - `OURS`：所有交易手续费（含中间行费用）均由付款人承担。 enum: - SHARED - OURS PayoutDate: type: string format: date example: '2024-03-01' description: 系统尝试向受益人提交付款的日期。 BeneficiaryCreationRequest: type: object discriminator: propertyName: entity_type mapping: INDIVIDUAL: $ref: '#/components/schemas/IndividualBeneficiaryCreation' COMPANY: $ref: '#/components/schemas/CompanyBeneficiaryCreation' properties: entity_type: type: string description: 受益人实体的类型。 oneOf: - $ref: '#/components/schemas/CompanyBeneficiaryCreation' - $ref: '#/components/schemas/IndividualBeneficiaryCreation' IsPayer: type: string example: 'N' description: | **重要提示：** **此字段计划在下一版本中弃用。建议在新开发中避免使用此字段。** 当前用户是否为付款人。 取值为 Y 或 N CreationPayerId: type: string example: d36384c8-5df1-4ede-b054-804578601ae7 format: uuid description: > **重要提示：** **此字段计划在下一版本中弃用。建议在新开发中避免使用此字段。** 付款人的唯一标识符。如果 `is_payer` 为 `Y`，`payer_id` 为空；如果 `is_payer` 为 `N`，则通过查询付款人列表接口获取 payer_id。 PayoutDocumentationItem: type: object properties: file: type: string format: base64-encoded example: >- data:image/png;base64,TG9yZW0gaXBzdW0gZG9sb3Igc2l0IGFtZXQsIGNvbnNlY3RldHVyIGFkaXBpc2NpbmcgZWxpdC4= description: 必须以 "data:image/jpeg;base64," 之类的前缀开头，后接实际的 base64 编码内容。 file_id: type: string format: uuid example: 5135e6cc-28b6-4889-81dc-3b86a09e1395 description: 证件的文件 ID，文件 ID 由文件上传 API 生成。 PayoutId: type: string format: uuid example: b3d9d2d5-4c12-4946-a09d-953e82sed2b0 description: 该 payout 的唯一标识符。 ShortReferenceId: type: string example: P220406-LLCVLRM description: 系统生成的用于标识该实体的编号。 PayoutStatus: type: string description: | 该 payout 的状态。 - `READY_TO_SEND`：payout 已通过校验，准备处理。 - `PENDING`：payout 正在由系统处理中。 - `REJECTED`：payout 因未满足校验或合规要求而被拒绝。 - `FAILED`：payout 处理过程中发生错误，无法完成。 - `COMPLETED`：payout 已成功处理，资金已转出。 enum: - READY_TO_SEND - PENDING - REJECTED - FAILED - COMPLETED IndividualBeneficiaryCreation: title: INDIVIDUAL type: object required: - entity_type - first_name - last_name - payment_method - bank_details - address properties: email: $ref: '#/components/schemas/BeneficiaryEmail' entity_type: $ref: '#/components/schemas/IndividualEntityType' payment_method: $ref: '#/components/schemas/PaymentMethod' nickname: $ref: '#/components/schemas/BeneficiaryNickname' first_name: $ref: '#/components/schemas/FirstName' last_name: $ref: '#/components/schemas/LastName' id_number: $ref: '#/components/schemas/BeneficiaryIdNumber' bank_details: $ref: '#/components/schemas/BeneficiaryBankDetails' address: $ref: '#/components/schemas/BeneficiaryAddress' additional_info: $ref: '#/components/schemas/BeneficiaryAdditionalInfo' CompanyBeneficiaryCreation: title: COMPANY type: object required: - entity_type - company_name - payment_method - bank_details - address properties: email: $ref: '#/components/schemas/BeneficiaryEmail' entity_type: $ref: '#/components/schemas/CompanyEntityType' company_name: $ref: '#/components/schemas/BeneficiaryCompanyName' payment_method: $ref: '#/components/schemas/PaymentMethod' nickname: $ref: '#/components/schemas/BeneficiaryNickname' bank_details: $ref: '#/components/schemas/BeneficiaryBankDetails' address: $ref: '#/components/schemas/BeneficiaryAddress' additional_info: $ref: '#/components/schemas/BeneficiaryAdditionalInfo' BeneficiaryEmail: type: string example: example@uqpay.com description: 受益人的电子邮箱地址。 IndividualEntityType: type: string example: INDIVIDUAL default: INDIVIDUAL PaymentMethod: type: string example: LOCAL description: | 需要指定支付方式，以确保针对该支付方式采集并校验准确的银行信息。 - `LOCAL`：通过本地清算系统的境内支付网络处理的付款。 - `SWIFT`：通过 SWIFT 网络处理的跨境国际付款。 enum: - LOCAL - SWIFT BeneficiaryNickname: type: string example: John Doe description: 受益人昵称。 maxLength: 120 FirstName: type: string example: John description: > 受益人的名字，仅当 entity_type 为 INDIVIDUAL 时存在。 - 当 `payment_method = SWIFT` 时： * 仅可包含英文字母、数字、特殊字符（半角格式）和空格。 * 允许的特殊字符：`-_().,@#~ ! $ % ^ & * + = { } [ ] \ | : " ' < > ? /・……` - 当 `payment_method = LOCAL` 时： * 不应用严格的校验规则，支持本地语言字符。 - 当 `bank_details.bank_country_code = SG` 且 `bank_details.account_currency_code = SGD` 时无需传入此字段 maxLength: 45 pattern: ^[a-zA-Z0-9 -_().,@#~!$%^&*+={}\|:"'<>?/・……]*$ LastName: type: string example: Doe description: > 受益人的姓氏，仅当 entity_type 为 INDIVIDUAL 时存在。 - 当 `payment_method = SWIFT` 时： * 仅可包含英文字母、数字、特殊字符（半角格式）和空格。 * 允许的特殊字符：`-_().,@#~ ! $ % ^ & * + = { } [ ] \ | : " ' < > ? /・……` - 当 `payment_method = LOCAL` 时： * 不应用严格的校验规则，支持本地语言字符。 - 当 `bank_details.bank_country_code = SG` 且 `bank_details.account_currency_code = SGD` 时无需传入此字段 maxLength: 45 pattern: ^[a-zA-Z0-9 -_().,@#~!$%^&*+={}\|:"'<>?/・……]*$ BeneficiaryIdNumber: type: string example: '110101199001011234' description: | 个人受益人的身份证件号码。 当受益人为中国大陆居民且满足以下条件时必填： - `bank_details.account_currency_code` 为 `CNH` - `payment_method` 为 `LOCAL` BeneficiaryBankDetails: type: object required: - bank_name - bank_address - bank_country_code - account_holder - account_currency_code - clearing_system - swift_code properties: bank_name: $ref: '#/components/schemas/BankName' bank_address: $ref: '#/components/schemas/BankAddress' bank_country_code: $ref: '#/components/schemas/CountryCode' account_holder: $ref: '#/components/schemas/AccountHolder' account_currency_code: $ref: '#/components/schemas/Currency' account_number: $ref: '#/components/schemas/AccountNumber' iban: $ref: '#/components/schemas/Iban' swift_code: $ref: '#/components/schemas/SwiftCode' clearing_system: $ref: '#/components/schemas/ClearingSystem' routing_code_type1: $ref: '#/components/schemas/RoutingCodeType1' routing_code_value1: $ref: '#/components/schemas/RoutingCodeValue1' routing_code_type2: $ref: '#/components/schemas/RoutingCodeType2' routing_code_value2: $ref: '#/components/schemas/RoutingCodeValue2' BeneficiaryAddress: type: object required: - country - city - street_address - postal_code - state description: > 受益人的地址。 - 当 `bank_details.bank_country_code = SG` 且 `bank_details.account_currency_code = SGD` 时无需传入此字段 properties: country: $ref: '#/components/schemas/CountryCode' nationality: $ref: '#/components/schemas/BeneficiaryNationality' city: $ref: '#/components/schemas/City' street_address: $ref: '#/components/schemas/StreetAddress' postal_code: $ref: '#/components/schemas/PostalCode' state: $ref: '#/components/schemas/State' BeneficiaryAdditionalInfo: type: object description: | 受益人的附加信息。 properties: organization_code: $ref: '#/components/schemas/OrganizationCode' proxy_id: $ref: '#/components/schemas/ProxyId' id_type: type: string example: PASSPORT description: > 个人受益人的身份证件类型。 - 当 bank_details.account_currency_code = COP 且 entity_type = INDIVIDUAL 时必填。 enum: - PASSPORT - NATIONAL_ID - DRIVERS_LICENSE id_number: type: string example: AB1234567 description: > 个人受益人的身份证件号码。 - 当 bank_details.account_currency_code = COP 且 entity_type = INDIVIDUAL 时必填。 tax_id: type: string example: '123456789' description: > 企业受益人的税务识别号。 - 当 bank_details.account_currency_code = COP 且 entity_type = COMPANY 时必填。 msisdn: type: string example: '+65111111' description: > 国际格式（含国家/地区码）的手机号码。 - 格式：+[country_code][phone_number]，如 +65111111。 - 当 bank_details.account_currency_code = COP 时必填。 - 当 bank_details.account_currency_code = HKD 且 clearing_system = LOCAL 时必填 CompanyEntityType: type: string example: COMPANY default: COMPANY BeneficiaryCompanyName: type: string example: UQPAY TECHNOLOGY SG PTE LTD description: > 受益人的公司名称，仅当 entity_type 为 COMPANY 时存在。 - 当 `payment_method = SWIFT` 时： * 仅可包含英文字母、数字、特殊字符（半角格式）和空格。 * 允许的特殊字符：`-_().,@#~ ! $ % ^ & * + = { } [ ] \ | : " ' < > ? /・……` - 当 `payment_method = LOCAL` 时： * 不应用严格的校验规则，支持本地语言字符。 - 当 `bank_details.bank_country_code = SG` 且 `bank_details.account_currency_code = SGD` 时无需传入此字段 - 当 `bank_country_code = CN` 且 `account_currency_code = CNH` 且 `payment_method = LOCAL` 且 `entity_type = COMPANY` 时，支持中文字符和中文括号 `（）`。 maxLength: 120 pattern: ^[a-zA-Z0-9 -_().,@#~!$%^&*+={}\|:"'<>?/・……]*$ BankName: type: string example: Bank of America description: 银行名称。 maxLength: 240 BankAddress: type: string example: 123 Main St description: 银行地址。 maxLength: 240 CountryCode: type: string example: SG description: >- 两位字母国家/地区代码 [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)。 maxLength: 2 minLength: 2 AccountHolder: type: string example: John Doe description: > 受益人银行账户的账户持有人名称。 - 当 `payment_method = SWIFT` 时： * 仅可包含英文字母、数字、特殊字符（半角格式）和空格。 * 允许的特殊字符：`-_().,@#~ ! $ % ^ & * + = { } [ ] \ | : " ' < > ? /・……` - 当 `payment_method = LOCAL` 时： * 不应用严格的校验规则，支持本地语言字符。 - 当 `entity_type = INDIVIDUAL`、`bank_details.bank_country_code = SG` 且 `bank_details.account_currency_code = SGD` 时，应用另一套校验规则： * `account_holder` 只能包含英文字母（A–Z、a–z）和空格。 * 长度必须在 2 到 140 个字符之间。 * 至少需要一个空格来分隔名和姓。 - 如果 `bank_country_code = CN`、`account_currency_code = CNH` 且 `payment_method = LOCAL`，请按当地银行要求以**中文字符**提供账户持有人名称。 * 此外，当 `entity_type = COMPANY` 时，也支持中文括号 `（）`。 maxLength: 240 pattern: ^[a-zA-Z0-9 _().,@#~!$%^&*+={}\|:"'<>?/・……]*$ Currency: type: string example: USD description: >- 受益人银行账户中持有资金的币种。三位字母 [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) 币种代码。 maxLength: 3 minLength: 3 AccountNumber: type: string example: '12345678' description: | 账号，多用于非欧洲国家/地区，account_number 与 iban 须填写其一。 仅允许英文字母（大小写）和数字；不允许使用短横线或其他特殊字符。 pattern: ^[a-zA-Z0-9]*$ maxLength: 60 Iban: type: string example: GB82 WEST 1234 5698 7654 32 description: > 对于以下国家/地区，**IBAN 为必填**（主要适用于欧洲及部分其他国家/地区）： **国家/地区代码**： `AL`, `AD`, `AT`, `AZ`, `BH`, `BY`, `BE`, `BA`, `BR`, `BG`, `CR`, `HR`, `CY`, `CZ`, `DK`, `DO`, `EG`, `SV`, `EE`, `FO`, `FI`, `FR`, `GE`, `DE`, `GI`, `GR`, `GL`, `GT`, `VA`, `HU`, `IS`, `IQ`, `IE`, `IL`, `IT`, `JO`, `KZ`, `XK`, `KW`, `LV`, `LB`, `LY`, `LI`, `LT`, `LU`, `MT`, `MR`, `MU`, `MD`, `MC`, `ME`, `NL`, `MK`, `NO`, `PK`, `PS`, `PL`, `PT`, `QA`, `RO`, `LC`, `SM`, `ST`, `SA`, `RS`, `SC`, `SK`, `SI`, `ES`, `SD`, `SE`, `CH`, `TL`, `TN`, `TR`, `UA`, `AE`, `GB`, `VG`. 如果受益人银行位于上述任一国家/地区，**必须提供 IBAN**。 maxLength: 36 SwiftCode: type: string example: WELGBE22 description: 受益人银行账户的 SWIFT 代码。 maxLength: 30 ClearingSystem: type: string example: GIRO description: | 指定该交易使用的清算系统。可选项因币种而异，对应当地的支付基础设施。 - **USD:** `ACH`, `Fedwire`, `SWIFT` - **SGD:** `FAST`, `GIRO`, `RTGS`, `SWIFT`, `PayNow` - **CNH:** `LOCAL`, `SWIFT` - **HKD:** `ACH`, `FPS`, `RTGS`, `SWIFT` - **EUR:** `LOCAL`, `SWIFT` - **CAD:** `EFT`, `Interac e-Transfer`, `SWIFT`, `Bill Payment` - **MYR:** `LOCAL` - **GBP:** `Faster Payments`, `CHAPS`, `SWIFT` - **IDR:** `LOCAL` - **JPY:** `LOCAL`, `SWIFT` - **NZD:** `Bank Transfer`, `SWIFT` - **AUD:** `Bank Transfer`, `SWIFT` maxLength: 30 RoutingCodeType1: type: string example: aba description: | 路由代码类型，必须为以下之一： * `ach` —— 当 account_currency_code = "USD" 且 clearing_system = "ACH" 时必填。 * `aba` - 当 account_currency_code = "USD" 且 clearing_system = "FEDWIRE" 时必填。 - 当 account_currency_code = "USD" 且 clearing_system = "SWIFT" 且 bank_country_code = "US" 时必填 * `bank_code` —— 当 account_currency_code = "CAD" 且 clearing_system = "EFT"，或 account_currency_code = "HKD" 且 clearing_system = "LOCAL" 时必填。 * `sort_code` —— 当 account_currency_code = "GBP" 且 clearing_system = "FASTER PAYMENTS" 时必填。**必须恰好为 6 位数字。** * `bsb_code` —— 当 account_currency_code = "AUD" 且 clearing_system = "LOCAL" 时必填。 * `ifsc` —— 当 account_currency_code = "INR" 且 clearing_system = "IFSC" 时必填。 * `cnaps_number` —— 当 account_currency_code = "CNH" 且 bank_country_code = "CN" 时必填。 maxLength: 12 RoutingCodeValue1: type: string example: '123456789' description: 清算路由代码的值。对应 routing_code_type_1 的路由代码。如果提供，也应同时提供 routing_code_type_1。 maxLength: 48 RoutingCodeType2: type: string example: ach description: | 路由代码子类型。 * `branch_code` —— 当 account_currency_code = "CAD" 且 clearing_system = "EFT" 时必填。 maxLength: 12 RoutingCodeValue2: type: string example: '123456789' description: >- 清算路由代码子类型的值。对应 routing_code_type_2 的路由代码。如果提供，也应同时提供 routing_code_type_2。 maxLength: 48 BeneficiaryNationality: type: string example: SG description: | 表示受益人国籍的两位字母国家/地区代码。 maxLength: 2 minLength: 2 City: type: string example: Singapore description: > 受益人所在城市。 用于请求校验时，非空值必须匹配正则 `^[A-Za-z0-9\s\-_().,:@#~!$%^&*+={}\[\]\\|"'<>?/・……]+$`。该规则适用于所有币种和支付方式。 空字符串和未传字段会跳过字符正则校验；该字段是否必填，仍由对应接口和 payout 场景已有的必填规则决定。 maxLength: 36 pattern: ^[A-Za-z0-9\s\-_().,:@#~!$%^&*+={}\[\]\\|"'<>?/・……]+$ StreetAddress: type: string example: 123 Main St description: > 受益人所在街道。 用于请求校验时，非空值必须匹配正则 `^[A-Za-z0-9\s\-_().,:@#~!$%^&*+={}\[\]\\|"'<>?/・……]+$`。该规则适用于所有币种和支付方式。 空字符串和未传字段会跳过字符正则校验；该字段是否必填，仍由对应接口和 payout 场景已有的必填规则决定。 maxLength: 255 pattern: ^[A-Za-z0-9\s\-_().,:@#~!$%^&*+={}\[\]\\|"'<>?/・……]+$ PostalCode: type: string example: '123456' description: 受益人的邮编。 maxLength: 12 State: type: string example: CA description: > 受益人所在州/省。 用于请求校验时，非空值必须匹配正则 `^[A-Za-z0-9\s\-_().,:@#~!$%^&*+={}\[\]\\|"'<>?/・……]+$`。该规则适用于所有币种和支付方式。 空字符串和未传字段会跳过字符正则校验；该字段是否必填，仍由对应接口和 payout 场景已有的必填规则决定。 maxLength: 96 pattern: ^[A-Za-z0-9\s\-_().,:@#~!$%^&*+={}\[\]\\|"'<>?/・……]+$ OrganizationCode: type: string example: 91210106MA0P46BWXY description: 分配给该组织的统一社会信用代码。此字段适用于在中国大陆注册的公司。 ProxyId: type: string description: PayNow 代理标识（SGD）。取值支持 UEN、电话号码或 VPA。 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。 ````