# 通过收款方ID发起打款

> 使用已审核通过的收款人 ID 发起 Transfer 打款。

```yaml
openapi: 3.1.0
info:
  title: 通过收款方ID发起打款
  version: 1.0.0
  description: 使用已审核通过的收款人 ID 发起 Transfer 打款。
paths:
  /api/v1/txn/remittance:
    post:
      summary: 通过收款方ID发起打款
      description: 使用已审核通过的收款人 ID 发起 Transfer 打款。
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                merchantNo:
                  type: string
                  description: Onerway 分配的商户号。通常在沙盒或生产商户开通后，从商户后台或开户材料中获取。
                payerId:
                  type: string
                  description: 本次打款使用的已保存付款方 ID。若付款方已预先创建且无需随单内联传递，优先使用该字段。
                  x-onerway-required: conditional
                  x-onerway-condition:
                    - 需在 `payerId` 和 `payerDetail` 之间二选一。
                payerDetail:
                  type: string
                  description: 以 JSON 字符串编码的付款方详情。适用于未预创建付款方，或需要按本次请求携带最新付款方信息的场景。
                  contentMediaType: application/json
                  contentSchema:
                    type: object
                    properties:
                      createTime:
                        type: string
                        description: createTime 字段。
                      merchantNo:
                        type: string
                        description: merchantNo 字段。
                      country:
                        type: string
                        description: country 字段。
                      addressEn1:
                        type: string
                        description: addressEn1 字段。
                      addressEn2:
                        type: string
                        description: addressEn2 字段。
                      addressEn3:
                        type: string
                        description: addressEn3 字段。
                      postcode:
                        type: string
                        description: postcode 字段。
                      status:
                        type: number
                        description: status 字段。
                      email:
                        type: string
                        description: email 字段。
                      areaCode:
                        type: string
                        description: areaCode 字段。
                      phoneNumber:
                        type: string
                        description: phoneNumber 字段。
                      state:
                        type: string
                        description: state 字段。
                      city:
                        type: string
                        description: city 字段。
                      subEntityType:
                        type: string
                        description: subEntityType 字段。
                      firstName:
                        type: string
                        description: firstName 字段。
                      lastName:
                        type: string
                        description: lastName 字段。
                      idType:
                        type: string
                        description: idType 字段。
                      idNumber:
                        type: string
                        description: idNumber 字段。
                      birthDate:
                        type: string
                        description: birthDate 字段。
                      idValidDateFrom:
                        type: string
                        description: idValidDateFrom 字段。
                      idValidDateTo:
                        type: string
                        description: idValidDateTo 字段。
                  x-onerway-required: conditional
                  x-onerway-condition:
                    - 需在 `payerDetail` 和 `payerId` 之间二选一。
                  x-onerway-format: json_string
                beneficiaryId:
                  type: string
                  description: 本次打款使用的已审核通过收款方 ID。
                sourceAmount:
                  type: number
                  description: 扣费前的源金额。按扣款侧金额驱动打款计算时使用该字段。
                  x-onerway-required: conditional
                  x-onerway-condition:
                    - 当 `chargeFlag=N` 时必填。
                sourceCurrency:
                  type: string
                  description: 本次打款的源币种。
                targetAmount:
                  type: number
                  description: 收款方币种下的预计到账金额。按收款侧到账金额驱动打款计算时使用该字段。
                  x-onerway-required: conditional
                  x-onerway-condition:
                    - 当 `chargeFlag=Y` 时必填。
                targetCurrency:
                  type: string
                  description: 收款方或目标币种。
                requestId:
                  type: string
                  description: 商户请求流水号；每笔打款请求应保持唯一，用于对账和幂等追踪。
                reference:
                  type: string
                  description: 打款附言或备注；在支持的渠道中，可用于下游对账或收款方账单展示。
                transactionPurpose:
                  type: string
                  description: 交易用途代码。应与实际业务用途和合规申报要求保持一致。
                chargeFlag:
                  type: string
                  description: 全额到账标识，用于决定按目标金额还是按源金额驱动计算。
                feeBearing:
                  type: string
                  description: SWIFT 手续费承担方式。
                  x-onerway-required: conditional
                  x-onerway-condition:
                    - SWIFT 打款且需要声明手续费承担方式时必填。
                sign:
                  type: string
                  description: 请求签名字符串，需使用商户私钥按 Transfer 请求签名规则生成。
              required:
                - merchantNo
                - beneficiaryId
                - sourceCurrency
                - targetCurrency
                - requestId
                - transactionPurpose
                - chargeFlag
                - sign
            examples:
              transfer-by-beneficiary-id:
                summary: 通过收款人 ID 发起打款
                value:
                  beneficiaryId: "1953727182141784064"
                  chargeFlag: Y
                  merchantNo: "801040"
                  payerId: "1953712585351499776"
                  reference: REFERENCE PAYOUT
                  requestId: DM2025081120520
                  sign: "{{SIGN}}"
                  sourceAmount: 113
                  sourceCurrency: USD
                  targetAmount: 1901
                  targetCurrency: PKR
                  transactionPurpose: "4"
              transfer-by-beneficiary-id-with-payer-detail:
                summary: 使用内联付款方资料发起打款
                value:
                  beneficiaryId: "1953727182141784064"
                  chargeFlag: N
                  merchantNo: "801040"
                  payerDetail: '{"subEntityType":"1","country":"US","addressEn1":"99 Demo
                    Street","postcode":"10001","email":"payer@example.com","areaCode":"+1","phoneNumber":"5550001234","state":"NEW
                    YORK","city":"NEW
                    YORK","idType":"SSN","idNumber":"replace_with_id_number","idValidDateTo":"2035-12-31"}'
                  reference: INLINE PAYER PAYOUT
                  requestId: DM2025081120521
                  sign: "{{SIGN}}"
                  sourceAmount: 100
                  sourceCurrency: USD
                  targetCurrency: USD
                  transactionPurpose: "3"
      responses:
        "200":
          description: 打款请求已受理
          content:
            application/json:
              schema:
                type: object
                properties:
                  respCode:
                    type: string
                    description: Onerway 返回的响应码。
                  respMsg:
                    type:
                      - string
                      - "null"
                    description: Onerway 返回的响应信息。
                    x-onerway-value:
                      nullable: true
                      when:
                        en: No response message is returned.
                        zh: 未返回响应信息时为 `null`。
                  data:
                    type: object
                    properties:
                      merchantNo:
                        type: string
                        description: 商户号。
                      payoutId:
                        type: string
                        description: Onerway 返回的打款流水 ID。
                      status:
                        type: string
                        description: 请求受理后的初始打款状态。最终成功或失败仍需通过 webhook 或查询接口确认。
                      requestId:
                        type: string
                        description: 响应中回显的商户请求流水号。
                    description: 已创建的打款记录。
              examples:
                transfer-accepted:
                  summary: 打款请求已受理
                  value:
                    respCode: "20000"
                    respMsg: null
                    data:
                      merchantNo: "801129"
                      payoutId: "1984136974445449216"
                      status: A
                      requestId: CYPW20251031055450
                transfer-validation-failed:
                  summary: 因参数问题被拒绝的打款请求
                  value:
                    respCode: "1001"
                    respMsg: "Parameter error: targetAmount is required when chargeFlag=Y"
                    data: null
```