收款下单

创建 PIX 支付订单并获取二维码内容。

接口

POST /cashin/pix/create-qrcode

认证

Merchant Credential。详见 认证。

接口背景

本接口用于创建巴西 Pix 动态收款二维码订单。商户提交自有订单和支付金额，Adopay 完成请求验签、参数及幂等校验后，创建收款订单并返回 Pix 二维码字符串。

商户应保证商户订单号在同一商户代收订单范围内唯一。商户订单号作为幂等键，幂等有效期为 3 个月：有效期内重复提交同一订单号不会重复创建收款订单。代收与代付的幂等互不排斥，代收上送的订单号可在代付中重复使用。同步响应成功仅表示二维码创建成功、订单进入待支付状态；最终支付结果以异步通知或收款订单查询结果为准。

二维码下单交易流程

• 同步下单阶段：用户提交订单，商户向 Adopay 申请创建二维码，并向用户展示返回的二维码或复制支付码。
• 异步支付阶段：用户通过付款银行完成 Pix 支付，央行 BCB 将支付结果通知 Adopay，Adopay 更新订单后通知商户。

sequenceDiagram
    autonumber
    actor U as 用户
    participant M as 商户
    participant A as Adopay
    participant PB as 付款银行
    participant BCB as 央行 BCB
    U->>M: 提交订单
    M->>A: POST /cashin/pix/create-qrcode
    A->>A: 验签、参数及幂等校验，创建订单和二维码
    A-->>M: 返回 platOrderNo、qrcode、expireTime
    M-->>U: 展示二维码或复制支付码
    U->>PB: 扫码或粘贴支付码并确认付款
    PB->>BCB: 提交 Pix 支付
    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	是	商户订单号；同一商户下代收订单号唯一。代收与代付幂等不互斥，代付可复用同一订单号。
expireTime	Body	int	19	否	订单过期截止时间，Unix 秒级时间戳；传值时间范围比当前时间大1分钟到24小时。如果不传则默认是30分钟。
mustPayerTaxNo	Body	string	64	否	必须匹配的付款人税号；实际付款人税号不一致时应拒绝入账。
amount	Body	decimal(25,2)	25,2	是	支付金额，单位为 BRL，必须大于 0，最多保留两位小数。
notifyUrl	Body	string	255	否	商户接收支付结果通知的地址。优先使用上送，其次使用商户配置url。
attach	Body	string	128	否	商户透传数据；回调通知或订单查询时原样返回，付款用户不可见。
reference	Body	string	128	否	用户账单明细中可见的描述，最多 128 个字符。

请求示例报文

请求头示例：

POST /cashin/pix/create-qrcode 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.5,
  "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.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",
    "merchantOrderNo": "PIX20260816000001",
    "amount": 125.5,
    "platOrderNo": "BIA202608160000000001",
    "expireTime": 1790200300,
    "qrcode": "00020101021226890014br.gov.bcb.pix2567pix.example.com/qr/v2/7f4a9c1e5204000053039865406125.505802BR5901N6009SAO PAULO62070503***6304ABCD"
  }
}