付款请求

创建 PIX 代付订单。

接口

POST /cashout/pix/create

认证

Merchant Credential。详见 认证。

接口背景

本接口用于发起巴西 Pix 付款交易。商户提交自有付款订单、金额及收款方信息，currency 支持 BRL，最终以当地货币向收款人付款。

同步返回 status = 200 只表示付款申请已被 Adopay 受理，不表示资金已经到达收款人账户。最终结果以异步通知或付款订单查询结果为准。

商户应保证同一商户下代付订单号唯一，用于订单防重及后续查询。商户订单号作为幂等键，幂等有效期为 3 个月：有效期内重复提交同一订单号不会重复创建代付订单。代收与代付的幂等互不排斥，代付上送的订单号可在代收中重复使用。

付款交易流程

• 同步受理阶段：商户提交付款申请，Adopay 完成接入校验、业务校验、幂等控制及订单落库后返回受理结果。
• 异步出款阶段：Adopay 在后台向央行 BCB 发起 Pix 出款指令，经收款银行完成入账，并将最终结果通知商户。

sequenceDiagram
    autonumber
    actor U as 用户（收款人）
    participant M as 商户
    participant A as Adopay
    participant BCB as 央行 BCB
    participant RB as 收款银行
    U->>M: 触发收款业务场景
    M->>A: POST /cashout/pix/create
    A->>A: 验签、业务及幂等校验，创建付款订单和出款任务
    A-->>M: 返回 platOrderNo、orderStatus = PENDING
    M-->>U: 展示申请已受理或处理中
    A->>BCB: 提交 Pix 付款指令
    BCB->>RB: 发起 Pix 转账
    RB-->>U: 收款账户入账
    RB-->>BCB: 返回入账结果
    BCB-->>A: 通知付款成功或失败结果
    A->>A: 校验结果并幂等更新订单终态
    A-->>M: POST 付款结果至 notifyUrl
    alt 商户成功确认
        M-->>A: 返回成功确认
        M-->>U: 更新业务订单并展示付款结果
    else 商户未成功确认
        A-->>M: 按通知任务策略重试
    end

接口请求字段

字段名	位置	类型	字段长度	是否必填	说明
X-Merchant-Id	Header	string	64	是	商户号，从请求头读取。
X-Timestamp	Header	int	19	是	Unix 秒级请求时间戳。
X-Nonce	Header	string	64	是	请求防重放随机字符串。
Digest	Header	string	52	是	请求体摘要，格式为 SHA-256=<Base64摘要>。
Authorization	Header	string	不定长	是	ES256 请求签名信息，其中 keyId 为商户密钥版本号。
merchantOrderNo	Body	string	64	是	商户订单号；同一商户下代付订单号唯一，用于订单防重及后续查询。代收与代付幂等不互斥，代收可复用同一订单号。
amount	Body	decimal	25,2	是	支付金额，单位为 BRL，必须大于零，最多两位小数。
payeeTaxNo	Body	string	64	是	收款人的税号；CPF 为 11 位数字，CNPJ 为 14 位数字。
payeePixKey	Body	string	64	是	收款人的 Pix Key。
notifyUrl	Body	string	255	否	商户接收代付结果通知的地址；优先使用上送，其次使用商户配置url。
attach	Body	string	128	否	商户透传数据；回调通知或调单查询时原样返回，付款用户不可见。
reference	Body	string	128	否	用户账单明细中可见的描述，最多 128 个字符。
displayName	Body	string	128	否	付款凭证上需要展示的名称。

请求头示例

Content-Type: application/json
X-Merchant-Id: 92315566000120
X-Timestamp: 1786838400
X-Nonce: 8f6e17d07f8b4fe19318d9c4dd6fc001
Digest: SHA-256=<REQUEST_BODY_SHA256_BASE64>
Authorization: Signature keyId="v1",alg="ES256",headers="(request-target) x-timestamp x-nonce digest",signature="<ES256_SIGNATURE_BASE64>"

其中，Digest 必须根据最终发送的原始请求体计算，Authorization 中的签名值必须根据实际请求路径、时间戳、Nonce 和 Digest 动态生成。

请求体示例报文

{
  "merchantOrderNo": "CASHOUT202608160001",
  "amount": 100.25,
  "payeePixKey": "maria.oliveira@example.com",
  "notifyUrl": "https://merchant.example.com/callback/cashout",
  "attach": "merchant-data-001",
  "reference": "Supplier payment",
  "displayName": "Maria Oliveira",
  "payeeTaxNo": "12345678901"
}

接口响应字段

接口使用统一的 status、msg、data 响应结构。status 为 200 表示接口受理成功，但不代表代付交易最终成功，最终结果应以 orderStatus、异步通知或订单查询结果为准。

字段名	类型	字段长度	是否必返	说明
status	int	4	是	响应码
msg	string	128	是	与 status 对应
data	object	不适用	否	代付受理结果；请求在进入业务处理前失败时可能不返回。
data.merchantOrderNo	string	64	是	商户订单号。
data.platOrderNo	string	64	是	平台代付订单号，用于平台侧订单跟踪和查询。
data.amount	decimal	25,2	是	商户提交的代付金额
data.receivedAmount	decimal	25,2	是	收款方实际到账金额；交易未完成时可能为 0。
data.orderStatus	string	16	是	代付订单当前状态；接口受理成功不等于该字段为成功状态。

orderStatus 枚举

枚举值	状态说明	是否终态
PENDING	处理中；代付申请已受理，资金处理尚未完成。	否
SUCCESS	代付成功；收款方已成功到账。	是
FAILED	代付失败；本次代付已结束，不会成功到账。	是

响应示例报文

{
  "status": 200,
  "msg": "sucesso",
  "data": {
    "merchantOrderNo": "CASHOUT202608160001",
    "platOrderNo": "APS202608160000000001",
    "amount": 100.25,
    "receivedAmount": 0,
    "orderStatus": "PENDING"
  }
}