> ## 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. # List Payouts > 获取 payout 交易列表。可通过指定创建日期范围或 payout 状态来筛选返回结果。 ##### 使用说明： - 如果 `start_time` 和 `end_time` 均省略，API 默认返回最近 30 天的 payout。 - 如果仅提供 `end_time`，则获取截至 `end_time` 前 30 天内的 payout。 ## OpenAPI ````yaml /zh/global-account/v1.6/banking.yaml get /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: get: tags: - Payouts summary: List Payouts description: | 获取 payout 交易列表。可通过指定创建日期范围或 payout 状态来筛选返回结果。 ##### 使用说明： - 如果 `start_time` 和 `end_time` 均省略，API 默认返回最近 30 天的 payout。 - 如果仅提供 `end_time`，则获取截至 `end_time` 前 30 天内的 payout。 operationId: list-payouts parameters: - $ref: '#/components/parameters/XOnBehalfOf' - $ref: '#/components/parameters/PageSize' - $ref: '#/components/parameters/PageNumber' - $ref: '#/components/parameters/PayoutStatus' - $ref: '#/components/parameters/StartTime' - $ref: '#/components/parameters/EndTime' responses: '200': description: OK —— 成功获取 payout 列表。 headers: x-response-id: $ref: '#/components/headers/XResponseId' content: application/json: schema: title: PayoutListResponse properties: total_pages: $ref: '#/components/schemas/TotalPages' total_items: $ref: '#/components/schemas/TotalItems' data: type: array items: $ref: '#/components/schemas/PayoutListResponse' 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 PageSize: name: page_size description: 每页返回的最大条目数。必须在 **10 到 100** 之间（含）。 in: query required: true schema: type: integer minimum: 1 maximum: 100 example: 10 PageNumber: name: page_number description: 用于获取特定一组条目的页码。必须 **大于等于 1**。 in: query required: true schema: type: integer minimum: 1 example: 1 PayoutStatus: name: payout_status description: 该 payout 的状态 in: query required: false schema: $ref: '#/components/schemas/PayoutStatus' StartTime: name: start_time description: '`created_time` 的开始时间，ISO8601 格式（含）。' in: query required: false schema: type: string example: '2024-03-01T00:00:00+08:00' EndTime: name: end_time description: '`created_time` 的结束时间，ISO8601 格式（含）。' in: query required: false schema: type: string example: '2024-03-01T00:00:00+08:00' headers: XResponseId: description: 响应的通用唯一标识符（UUID v4）。在与 UQPAY 支持团队沟通时有助于定位某个请求。 schema: type: string format: uuid example: 2adba88e-9d63-44bc-b975-9b6ae3440dde schemas: TotalPages: type: integer example: 10 description: 可用条目的总页数。 TotalItems: type: integer example: 105 description: 可用条目的总数。 PayoutListResponse: type: object required: - unique_request_id - payout_id - payout_currency - payout_amount - fee_paid_by - fee_currency - fee_amount - payout_date - short_reference_id - payout_reference - payout_reason - payout_status - create_time - update_time - complete_time - purpose_code properties: unique_request_id: $ref: '#/components/schemas/UniqueRequestId' payout_id: $ref: '#/components/schemas/PayoutId' payout_currency: $ref: '#/components/schemas/Currency' payout_amount: $ref: '#/components/schemas/Amount' fee_paid_by: $ref: '#/components/schemas/FeePaidBy' fee_currency: $ref: '#/components/schemas/FeeCurrency' fee_amount: $ref: '#/components/schemas/FeeAmount' payout_date: $ref: '#/components/schemas/PayoutDate' short_reference_id: $ref: '#/components/schemas/PayoutShortReferenceId' payout_reference: $ref: '#/components/schemas/PayoutReference' payout_reason: $ref: '#/components/schemas/PayoutReason' purpose_code: $ref: '#/components/schemas/PurposeCode' payout_status: $ref: '#/components/schemas/PayoutStatus' create_time: $ref: '#/components/schemas/CreateTime' description: 该 payout 的创建时间。 update_time: $ref: '#/components/schemas/UpdateTime' description: 该 payout 的更新时间。 complete_time: $ref: '#/components/schemas/CompleteTime' description: 该 payout 的完成时间。 failure_returned_amount: $ref: '#/components/schemas/FailureReturnedAmount' failure_reason: $ref: '#/components/schemas/FailureReason' quote_id: $ref: '#/components/schemas/QuoteId' conversion: $ref: '#/components/schemas/PayoutConversion' 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 UniqueRequestId: type: string format: uuid example: b3d9d2d5-4c12-4946-a09d-953e82sed2b0 description: 通用唯一标识符（UUID v4）。客户端将在 POST 操作中使用该标识符来创建资源。 PayoutId: type: string format: uuid example: b3d9d2d5-4c12-4946-a09d-953e82sed2b0 description: 该 payout 的唯一标识符。 Currency: type: string example: USD description: >- 受益人银行账户中持有资金的币种。三位字母 [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) 币种代码。 maxLength: 3 minLength: 3 Amount: type: string example: '1000.00' description: | 付款人将汇出的金额，以 `currency` 计。 FeePaidBy: type: string example: SHARED description: > 付款手续费的承担类型。仅在 `payment_method = SWIFT` 时生效并必填。 - `SHARED`：交易手续费由付款人与收款方分担；付款人承担汇出行费用，收款方承担收款行费用。当付款人为企业且付款人所在国家/地区为 SG、VN、HK 或 AU 之一时，SWIFT payout 可使用此项。 - `OURS`：所有交易手续费（含中间行费用）均由付款人承担。 enum: - SHARED - OURS FeeCurrency: type: string example: USD description: 用于支付手续费的币种。三位字母 [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) 币种代码。 maxLength: 3 minLength: 3 FeeAmount: type: string example: '1.00' description: 该 payout 的手续费金额。 PayoutDate: type: string format: date example: '2024-03-01' description: 系统尝试向受益人提交付款的日期。 PayoutShortReferenceId: type: string example: P220406-LLCVLRM description: 系统生成的用于标识该 payout 的编号。 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 时，不应用输入格式校验。 PayoutReason: type: string maxLength: 200 example: Audiovisual services description: 该 payout 的自定义事由，将显示在受益人的银行交易记录中。 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` - 工资/薪酬。 CreateTime: type: string format: date/time example: '2024-03-01T00:00:00+08:00' description: >- 记录在系统中创建时的时间戳。时间戳遵循 [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) 标准。 UpdateTime: type: string format: date/time example: '2024-03-01T00:00:00+08:00' CompleteTime: type: string format: date/time example: '2024-03-01T00:00:00+08:00' description: 请求成功处理并标记为 `COMPLETED` 时的时间戳。 FailureReturnedAmount: type: string example: '1000.00' description: 失败 payout 中待退回的金额。 FailureReason: type: string example: '' description: 该 payout 失败的原因。 QuoteId: type: string example: 784832f7-1f8a-4b08-ac2a-8719b5b2a590 description: > 预先创建的报价的 ID，通过[创建报价](/zh/global-account/v1.6/api-reference/create-quote)获取。 仅在跨币种 payout 场景下需要。 如果提供，还必须同时提供 `payout_currency` 和 `payout_amount`。 PayoutConversion: type: object description: | 该 payout 的换汇详情。 仅在跨币种 payout 场景下需要。 properties: currency_pair: type: string description: 该汇率对应的货币对。 example: USDEUR client_rate: type: string description: 该交易适用的汇率。 example: '1.355957' securitySchemes: XAuthToken: type: apiKey in: header name: x-auth-token description: 由 UQPay 提供的登录 API Token。 ````