/cashin/pix/create-qrcode-partner 接口介绍

接口背景

/cashin/pix/create-qrcode-partner 是支付网关提供给合作商的巴西 Pix 动态二维码预下单接口。合作商通过该接口提交订单、付款人、子商户及商品信息，完成请求验签、协议解析和报文转换后，调用预下单能力创建收款订单并返回 Pix 二维码字符串。

合作商应保证同一一级商户下的代收订单号唯一。商户订单号作为幂等键，幂等有效期为 3 个月：有效期内重复提交同一订单号不会重复创建收款订单。代收与代付的幂等互不排斥，代收上送的订单号可在代付中重复使用。接口同步返回二维码创建结果，后续支付结果以异步通知或订单查询结果为准。

二维码下单交易流程

二维码交易分为两个相互独立的阶段：

• 同步下单阶段：用户向合作商提交订单，合作商向 Adopay 申请创建二维码；Adopay 返回二维码后，由合作商向用户展示。
• 异步支付阶段：用户通过付款银行完成 Pix 支付，央行 BCB 将支付结果通知 Adopay，Adopay 完成订单处理后再通知合作商。

同步响应成功仅表示二维码创建成功、订单已进入待支付状态，不表示付款人已经支付成功。最终支付结果以 Adopay 异步通知或订单查询结果为准。

用户下单、扫码付款及异步支付结果流程

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

    Note over U,A: 用户下单及二维码创建（同步）
    U->>M: 选择商品或服务并提交订单
    M->>M: 创建商户订单
    M->>A: POST /cashin/pix/create-qrcode-partner
    A->>A: 验签、摘要校验、时间戳与防重放校验
    A->>A: 参数校验、幂等校验并创建 Adopay 订单
    A->>A: 创建 Pix 动态二维码
    A->>A: 保存订单、二维码标识和二维码码值
    A-->>M: 返回 platOrderNo、qrcode、expireTime
    M-->>U: 展示 Pix 二维码或复制支付码

    Note over U,BCB: 用户扫码付款及支付结果通知（异步）
    U->>PB: 扫码或粘贴支付码并确认付款
    PB->>BCB: 提交 Pix 支付
    BCB-->>A: 通知 Pix 支付结果
    A->>A: 校验支付结果并更新订单状态
    A-->>M: POST 支付结果至 notifyUrl
    alt 合作商成功确认
        M-->>A: 返回成功确认
        M-->>U: 更新订单状态并展示支付结果
    else 合作商未成功确认
        A-->>M: 按通知任务策略重试
    end

接口请求地址

项目	内容
请求方式	POST
请求路径	/cashin/pix/create-qrcode-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	是	商户订单号；同一一级商户下代收订单号唯一。代收与代付幂等不互斥，代付可复用同一订单号。
expireTime	Body	int	19	否	订单过期截止时间，Unix 秒级时间戳；传值时间范围比当前时间大1分钟到24小时。如果不传则默认是30分钟。
mustPayerTaxNo	Body	string	64	否	必须匹配的付款人税号；实际付款人税号不一致时应拒绝入账。
amount	Body	decimal(25,2)	25,2	是	支付金额，单位为 BRL，必须大于 0，最多保留两位小数。
subMerchantNo	Body	string	64	是	子商户号。
notifyUrl	Body	string	255	否	合作商接收支付结果通知的地址。优先使用上送，其次使用合作商配置url。
attach	Body	string	128	否	合作商透传数据；回调通知或订单查询时原样返回，付款用户不可见。
reference	Body	string	128	否	用户账单明细中可见的描述，最多 128 个字符。

请求示例报文

请求头示例：

POST /cashin/pix/create-qrcode-partner HTTP/1.1
Content-Type: application/json
X-Merchant-Id: 92315566000120
X-Timestamp: 1790200000
X-Nonce: 550e8400-e29b-41d4-a716-446655440000
Digest: SHA-256=<Base64摘要>
Authorization: Signature keyId="v1",alg="ES256",headers="(request-target) x-timestamp x-nonce digest",signature="<ES256_SIGNATURE_BASE64>"

请求 Body 示例：

{
  "merchantOrderNo": "PIX20260816000001",
  "expireTime": 1790200300,
  "mustPayerTaxNo": "12345678901",
  "amount": 125.50,
  "subMerchantNo": "SUB00000001",
  "notifyUrl": "https://merchant.example.com/notify/pix",
  "attach": "order-source=checkout",
  "reference": "Compra de produtos"
}

接口响应字段

接口使用统一的 status、msg、data 响应结构。status 为 200 表示动态二维码创建成功；其他值表示请求处理失败或订单仍处于处理中。

字段名	类型	字段长度	是否必返	说明
status	int	4	是	响应码
msg	string	128	是	与 status 对应
data	object	不适用	否	预下单响应数据；请求在进入业务处理前失败时可能不返回。
data.merchantNo	string	64	条件必返	一级商户号；进入预下单业务处理后返回。
data.subMerchantNo	string	64	条件必返	二级商户号，与请求中的 subMerchantNo 一致；进入预下单业务处理后返回。
data.merchantOrderNo	string	64	条件必返	商户订单号；进入预下单业务处理后返回。
data.amount	decimal(25,2)	25,2	条件必返	订单金额。
data.platOrderNo	string	64	成功必返	平台收款订单号。
data.expireTime	int	19	成功必返	订单过期截止时间，Unix 秒级时间戳。
data.qrcode	string	65535	成功必返	Pix 二维码字符串，可用于生成二维码或复制支付。

响应示例报文

成功响应示例：

{
  "status": 200,
  "msg": "sucesso",
  "data": {
    "merchantNo": "92315566000120",
    "subMerchantNo": "SUB00000001",
    "merchantOrderNo": "PIX20260816000001",
    "amount": 125.50,
    "platOrderNo": "BIA202608160000000001",
    "expireTime": 1790200300,
    "qrcode": "00020101021226890014br.gov.bcb.pix2567pix.example.com/qr/v2/7f4a9c1e5204000053039865406125.505802BR5901N6009SAO PAULO62070503***6304ABCD"
  }
}

响应错误码

• 响应状态

交易结果使用原则

• 下单接口返回 status = 200 只代表二维码创建成功，不代表支付成功。
• 二维码创建后、收到支付成功结果前，订单处于待支付或处理中状态。
• 合作商应同时接入异步通知和订单查询：异步通知用于及时更新订单，订单查询用于超时、漏通知或状态核对场景。
• 异步通知可能因网络重试而重复送达。合作商应以 platOrderNo 为主键，并结合通知事件和订单状态进行幂等处理，不能因重复通知重复入账或重复发货。
• 合作商收到支付成功通知后，应先验签，再校验商户订单号、Adopay 订单号、金额、币种和订单状态，全部一致后再执行发货或提供服务。
• 商户订单号作为代收幂等键，幂等有效期为 3 个月：有效期内重复提交同一订单号返回首次受理结果，不会重复创建收款订单。
• 代收与代付的幂等互不排斥：代收上送过的商户订单号，代付仍可上送同一订单号；同一订单号只在同一业务方向内要求唯一。