/cashout/pix/create-partner 代付接口介绍

接口背景

/cashout/pix/create-partner 提供给合作商的代付创建接口，当前用于发起巴西 Pix 代付交易。 currency 支持 BRL，最终向收款人付款时使用当地货币。

代付交易流程

代付交易分为两个相互衔接的阶段：

• 同步受理阶段：合作商向 Adopay 提交代付申请；Adopay 完成接入校验、业务校验、幂等控制及订单落库后，向合作商返回受理结果。
• 异步出款阶段：Adopay 在后台发起 Pix 出款指令到央行 BCB，央行 BCB 调用收款银行实现用户收款账户入账；

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

用户、合作商、Adopay、付款银行及央行 BCB 交易流程

sequenceDiagram
    autonumber
    actor U as 用户（收款人）
    participant M as 合作商
    participant A as Adopay
    participant PB as 央行 BCB
    participant BCB as 收款银行

    Note over U,A: 代付申请与Adopay 受理（同步）
    opt 由用户业务行为触发代付
        U->>M: 触发提现、退款、结算等收款场景
    end
    M->>M: 创建商户代付订单
    M->>A: POST /cashout/pix/create-partner
    A->>A: 验签、摘要校验、时间戳与防重放校验
    A->>A: 参数、合作商权限、账户及风控校验
    A->>A: 幂等校验并创建 Adopay 代付订单
    A->>A: 创建后台出款任务
    A-->>M: 返回 platOrderNo、orderStatus = PENDING
    M-->>U: 展示代付申请已受理或处理中

    Note over A,BCB: Pix 出款执行（异步）
    A->>PB: 提交 Pix 代付指令
    PB->>BCB: 发起 Pix 转账
    BCB-->>U: 经收款行将资金入账至用户账户

    Note over M,BCB: 最终结果回传与合作商通知（异步）
    BCB-->>PB: 返回入账结果
    PB-->>A: 通知代付成功或失败结果
    A->>A: 校验结果并幂等更新代付订单终态
    A-->>M: POST 代付结果至 notifyUrl
    alt 合作商成功确认
        M-->>A: 返回成功确认
        M-->>U: 更新业务订单并展示代付结果
    else 合作商未成功确认
        A-->>M: 按通知任务策略重试
    end

接口请求地址

项目	内容
请求方式	POST
请求路径	/cashout/pix/create-partner
Content-Type	application/json
接口用途	创建 Pix 代付订单

接口接入规范

• common接入规范

接口请求字段

字段名	位置	类型	字段长度	是否必填	说明
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。
subMerchantNo	Body	string	64	是	子商户号。
notifyUrl	Body	string	255	否	合作商接收代付结果通知的地址；优先使用上送，其次使用合作商配置url。
attach	Body	string	128	否	合作商透传数据；回调通知或调单查询时原样返回，付款用户不可见。
reference	Body	string	128	否	用户账单明细中可见的描述，最多 128 个字符。
displayName	Body	string	128	否	付款凭证上需要展示的名称。

请求头示例

POST /cashout/pix/create-partner HTTP/1.1
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,
  "payeeTaxNo": "12345678901",
  "payeePixKey": "maria.oliveira@example.com",
  "subMerchantNo": "SUBMERCHANT0001",
  "notifyUrl": "https://merchant.example.com/callback/cashout",
  "attach": "merchant-data-001",
  "reference": "Supplier payment",
  "displayName": "Maria Oliveira"
}

接口响应字段

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

字段名	类型	字段长度	是否必返	说明
status	int	4	是	响应码
msg	string	128	是	与 status 对应
data	object	不适用	否	代付受理结果；请求在进入业务处理前失败时可能不返回。
data.subMerchantNo	string	64	是	二级商户号，与请求中的 subMerchantNo 一致。
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": {
    "subMerchantNo": "SUBMERCHANT0001",
    "merchantOrderNo": "CASHOUT202608160001",
    "platOrderNo": "APS202608160000000001",
    "amount": 100.25,
    "receivedAmount": 0,
    "orderStatus": "PENDING"
  }
}

接口响应错误码

• 响应状态

交易结果使用原则

• status = 200 表示接口受理成功，不能作为代付成功或用户到账的依据。
• orderStatus = PENDING 表示订单仍在处理中；只有 SUCCESS 或 FAILED 才是当前代付流程的最终状态。
• 合作商应同时接入异步通知和订单查询：异步通知用于及时更新订单，订单查询用于同步超时、漏通知或状态核对场景。
• 银行或网络返回超时、未知结果时，合作商不得直接创建新订单；应使用原商户订单号查询或重试，避免重复出款。
• 异步通知可能因网络重试而重复送达。合作商应以 platOrderNo 为主键，并结合 merchantOrderNo 和订单状态进行幂等处理，不能因重复通知重复记账。
• 商户订单号作为代付幂等键，幂等有效期为 3 个月：有效期内重复提交同一订单号返回首次受理结果，不会重复创建代付订单。
• 代收与代付的幂等互不排斥：代付上送过的商户订单号，代收仍可上送同一订单号；同一订单号只在同一业务方向内要求唯一。
• 合作商收到成功通知后，应先验签，再核对商户订单号、平台订单号、金额、币种和订单状态；全部一致后再完成提现、退款、结算或其他业务状态更新。