> ## 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

> 创建新的出款单



## OpenAPI

````yaml /zh/global-acquiring/v1.6/payment.yaml post /v2/payment/payout/create
openapi: 3.0.2
info:
  title: Payment API
  version: 0.0.1
  x-source-en-commit: 821171b
  x-source-en-path: global-acquiring/v1.6/payment.yaml
  description: >
    UQPAY Payment API 让你接受付款、管理交易，并处理退款与出款。


    ## 功能概览

    - 使用卡、数字钱包和本地支付方式创建并确认 PaymentIntent

    - 处理全额和部分退款

    - 管理客户与已保存的支付方式

    - 创建出款与银行账户记录

    - 查询 PaymentAttempt、余额与交易历史


    ## 身份认证

    所有请求都需要携带有效的鉴权 Token，Token 通过 [Access
    Token](/zh/account-center/v1.6/api-reference/access-token) 接口获取。请在
    `x-auth-token` 请求头中携带该 Token。


    ## 幂等性

    POST 请求支持 `x-idempotency-key` 请求头，可在不重复创建资源的前提下安全重试。
  contact:
    name: UQPAY Support Team
    url: https://www.uqpay.com/support
    email: support@uqpay.com
  license:
    name: Proprietary
    url: https://www.uqpay.com/legal/api-terms
  termsOfService: https://www.uqpay.com/legal/terms
servers:
  - url: https://api-sandbox.uqpaytech.com/api
    description: 沙盒环境基础 URL。
  - url: https://api.uqpay.com/api
    description: 生产环境基础 URL。
security:
  - XAuthToken: []
tags:
  - name: Customers
    description: 创建和管理客户档案。客户对象保存支付方式和账单信息，可在多笔支付中复用。
  - name: Payment Intents
    description: >-
      PaymentIntent 引导你完成向客户收款的整个流程。建议你的系统中每个订单或客户会话只创建一个 PaymentIntent。之后可以引用该
      PaymentIntent，查看某次会话的 PaymentAttempt 历史。
  - name: Payment Attempts
    description: >-
      每当客户使用所选 PaymentMethod 付款时，都会创建一个 PaymentAttempt 对象。通过该 API
      可以了解客户是如何为订单付款的。
  - name: Payment Refunds
    description: >
      你可以创建多笔部分退款，直至累计达到原交易金额。每笔退款都会生成唯一记录，并自动校验可用余额。

      PaymentIntent 引导你完成向客户收款的整个流程。建议你的系统中每个订单或客户会话只创建一个 PaymentIntent。之后可以引用该
      PaymentIntent，查看某次会话的 PaymentAttempt 历史。
  - name: Payment Balances
    description: |
      支付余额管理让你查询不同币种的账户余额。你可以查询单个币种的余额，也可以分页查询所有币种的余额。
  - name: Payment Payouts
    description: |
      出款管理让你创建和管理用于资金划转的出款单。你可以创建出款、查询单笔出款，也可以分页并按条件筛选列出所有出款。
  - name: Terminal Management
    description: 用于 POS 设备注册和密钥管理的终端管理 API。
  - name: Bank Accounts
    description: |
      用于结算账户的银行账户管理 API。可创建、更新、查询和列出用于接收结算款项的银行账户。
paths:
  /v2/payment/payout/create:
    post:
      tags:
        - Payment Payouts
      summary: Create Payout
      description: 创建新的出款单
      operationId: create-payout
      parameters:
        - $ref: '#/components/parameters/XOnBehalfOf'
        - $ref: '#/components/parameters/XIdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PayoutCreateRequest'
      responses:
        '200':
          description: 成功创建出款
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PayoutResponse'
components:
  parameters:
    XOnBehalfOf:
      in: header
      name: x-on-behalf-of
      schema:
        type: string
      required: false
      description: >
        指定代表哪个子账户发起该请求。应设置为 `account_id`，可通过 [List Connected
        Accounts](/zh/account-center/v1.6/api-reference/list-connected-accounts)
        获取。若省略或为空，则使用主账户执行请求。

        更多信息见 [Connected
        Accounts](/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:
    PayoutCreateRequest:
      type: object
      required:
        - payout_currency
        - payout_amount
        - statement_descriptor
      properties:
        payout_currency:
          $ref: '#/components/schemas/Currency'
          example: SGD
        payout_amount:
          type: string
          description: 通过此次出款提取的金额。
          example: '100.00'
        internal_note:
          $ref: '#/components/schemas/InternalNote'
        statement_descriptor:
          $ref: '#/components/schemas/StatementDescriptor'
        payout_account_id:
          type: string
          description: |
            通过内部转账接收出款资金的 UQPAY 账户 ID。长、短账户 ID 均可接受。
            - 如省略，出款将发送至预先配置的外部银行账户（默认行为）。
            - 如提供，出款将作为 UQPAY 内部转账处理至指定账户。请传入调用方的账户 ID。
          example: 18523f72-f4de-4f9c-bb8e-ec7d1c4f32be
    PayoutResponse:
      type: object
      required:
        - payout_id
        - payout_currency
        - payout_amount
        - statement_descriptor
        - payout_status
        - create_time
      properties:
        payout_id:
          type: string
          description: 出款 UUID
          example: PO1968582687224500224
        payout_currency:
          $ref: '#/components/schemas/Currency'
          example: SGD
        payout_amount:
          type: string
          description: 通过此次出款提取的金额。
          example: '100.00'
        internal_note:
          $ref: '#/components/schemas/InternalNote'
        statement_descriptor:
          $ref: '#/components/schemas/StatementDescriptor'
        payout_status:
          $ref: '#/components/schemas/PayoutStatusEnum'
        create_time:
          $ref: '#/components/schemas/DateTime'
          description: 出款创建时间
          example: '2025-09-18T15:47:41+08:00'
        completed_time:
          $ref: '#/components/schemas/DateTime'
          description: 出款完成时间
          example: ''
    Currency:
      type: string
      description: 三位币种代码
    InternalNote:
      type: string
      description: 出款备注信息
      example: Payment to supplier
    StatementDescriptor:
      type: string
      description: 向收款方银行展示的出款参考信息
      maxLength: 15
      example: UQPAY PAYOUT
    PayoutStatusEnum:
      type: string
      description: |
        出款状态枚举。

        - `INITIATED`：出款已发起。
        - `PROCESSING`：出款正在处理中（银行处理中）。
        - `COMPLETED`：出款已成功完成。
        - `FAILED`：出款失败。
        - `FAILED_REFUNDED`：出款失败，资金已退回。
      enum:
        - INITIATED
        - PROCESSING
        - COMPLETED
        - FAILED
        - FAILED_REFUNDED
      example: INITIATED
    DateTime:
      type: string
      format: date/time
      example: '2024-03-01T00:00:00+08:00'
  securitySchemes:
    XAuthToken:
      type: apiKey
      in: header
      name: x-auth-token
      description: UQPay 提供的登录 API Token。

````