/cashin/pix/create-qrcode-partner Create Payment / QR Code

Background

/cashin/pix/create-qrcode-partner is the pre-order API that the payment gateway provides to partners for Brazilian PIX dynamic QR codes. Through this API the partner submits order, payer, sub-merchant, and product information; after request signature verification, protocol parsing, and message transformation, the platform invokes the pre-order capability to create the payment order and returns the PIX QR code string.

The partner must ensure that cashin order numbers are unique under the same primary merchant. The merchant order number serves as the idempotency key with a validity window of 3 months: resubmitting the same order number within the window does not create a duplicate payment order. Cashin and cashout idempotency are independent of each other; an order number submitted for cashin may be reused in cashout. The API returns the QR code creation result synchronously; the subsequent payment result is determined by the asynchronous notification or the order query result.

QR Code Ordering Transaction Flow

A QR code payment consists of two mutually independent phases:

• Synchronous ordering phase: the user submits an order to the partner, and the partner requests QR code creation from Adopay; after Adopay returns the QR code, the partner displays it to the user.
• Asynchronous payment phase: the user completes the PIX payment through their paying bank, the Central Bank (BCB) notifies Adopay of the payment result, and Adopay notifies the partner after finishing order processing.

A successful synchronous response only means the QR code was created and the order has entered the pending-payment state; it does not mean the payer has already paid. The final payment result is determined by the Adopay asynchronous notification or the order query result.

User Ordering, QR Code Payment, and Asynchronous Payment Result Flow

sequenceDiagram
    autonumber
    actor U as User
    participant M as Partner
    participant A as Adopay
    participant PB as Paying Bank
    participant BCB as Central Bank (BCB)

    Note over U,A: User places the order and the QR code is created (synchronous)
    U->>M: Selects a product or service and places the order
    M->>M: Creates the merchant order
    M->>A: POST /cashin/pix/create-qrcode-partner
    A->>A: Signature verification, digest check, timestamp and anti-replay checks
    A->>A: Parameter validation, idempotency check, and Adopay order creation
    A->>A: Creates the PIX dynamic QR code
    A->>A: Stores the order, QR code identifier, and QR code value
    A-->>M: Returns platOrderNo, qrcode, expireTime
    M-->>U: Displays the PIX QR code or copy-and-pay code

    Note over U,BCB: User scans and pays, and the payment result is notified (asynchronous)
    U->>PB: Scans the QR code or pastes the payment code and confirms payment
    PB->>BCB: Submits the PIX payment
    BCB-->>A: Notifies the PIX payment result
    A->>A: Verifies the payment result and updates the order status
    A-->>M: POSTs the payment result to notifyUrl
    alt Partner acknowledges successfully
        M-->>A: Returns a success acknowledgment
        M-->>U: Updates the order status and shows the payment result
    else Partner does not acknowledge successfully
        A-->>M: Retries per the notification task policy
    end

Endpoint

Item	Value
Method	POST
Path	/cashin/pix/create-qrcode-partner
Content-Type	application/json
Purpose	Create a Brazilian PIX dynamic QR code payment order

Access Requirements

• Common specifications

Request Fields

Field	Location	Type	Length	Required	Description
X-Merchant-Id	Header	string	64	Yes	Primary merchant ID, read from the request header.
X-Timestamp	Header	int	19	Yes	Unix request timestamp in seconds; used to validate request freshness.
X-Nonce	Header	string	64	Yes	Anti-replay random string for the request.
Digest	Header	string	52	Yes	Request body digest in the format SHA-256=<Base64 digest>.
Authorization	Header	string	-	Yes	ES256 request signature information, where keyId is the partner key version.
merchantOrderNo	Body	string	64	Yes	Merchant order number; unique among cashin orders under the same primary merchant. Cashin and cashout idempotency are independent: cashout may reuse the same order number.
expireTime	Body	int	19	No	Order expiration deadline, Unix timestamp in seconds; the value must be between 1 minute and 24 hours after the current time. Defaults to 30 minutes if omitted.
mustPayerTaxNo	Body	string	64	No	Tax ID that the payer must match; if the actual payer's tax ID differs, the payment must be rejected and not credited.
amount	Body	decimal(25,2)	25,2	Yes	Payment amount in BRL; must be greater than 0, with at most two decimal places.
subMerchantNo	Body	string	64	Yes	Sub-merchant ID.
notifyUrl	Body	string	255	No	URL where the partner receives the payment result notification. The submitted value takes priority; otherwise the partner's configured URL is used.
attach	Body	string	128	No	Data passed through by the partner; returned as-is in callback notifications and order queries, invisible to the paying user.
reference	Body	string	128	No	Description visible in the user's transaction statement, up to 128 characters.

Request Example

Request header example:

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 digest>
Authorization: Signature keyId="v1",alg="ES256",headers="(request-target) x-timestamp x-nonce digest",signature="<ES256_SIGNATURE_BASE64>"

Request body example:

{
  "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"
}

Response Fields

The API uses the standard status, msg, and data response structure. status = 200 means the dynamic QR code was created successfully; any other value means the request failed or the order is still being processed.

Field	Type	Length	Returned	Description
status	int	4	Yes	Response code
msg	string	128	Yes	Message corresponding to status
data	object	N/A	No	Pre-order response data; may be omitted when the request fails before entering business processing.
data.merchantNo	string	64	Conditional	Primary merchant ID; returned after pre-order business processing begins.
data.subMerchantNo	string	64	Conditional	Sub-merchant ID, identical to the subMerchantNo in the request; returned after pre-order business processing begins.
data.merchantOrderNo	string	64	Conditional	Merchant order number; returned after pre-order business processing begins.
data.amount	decimal(25,2)	25,2	Conditional	Order amount.
data.platOrderNo	string	64	On success	Platform cashin order number.
data.expireTime	int	19	On success	Order expiration deadline, Unix timestamp in seconds.
data.qrcode	string	65535	On success	PIX QR code string, which can be rendered as a QR code or used as a copy-and-pay code.

Response Example

Success response example:

{
  "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"
  }
}

Response Error Codes

• Response Status

Transaction Result Handling Principles

• A status = 200 from the ordering API only means the QR code was created successfully, not that the payment succeeded.
• After the QR code is created and before the payment success result arrives, the order remains in the pending or processing state.
• The partner should integrate both the asynchronous notification and the order query: the notification keeps orders up to date, and the query covers timeouts, missed notifications, and status reconciliation.
• Asynchronous notifications may be delivered more than once due to network retries. The partner must use platOrderNo as the primary key and apply idempotent processing together with the notification event and order status; duplicate notifications must not lead to duplicate crediting or duplicate fulfillment.
• Upon receiving a payment success notification, the partner should first verify the signature, then validate the merchant order number, Adopay order number, amount, currency, and order status, and only fulfill the order or provide the service after everything matches.
• The merchant order number is the cashin idempotency key with a validity window of 3 months: resubmitting the same order number within the window returns the result of the first acceptance and does not create a duplicate payment order.
• Cashin and cashout idempotency are independent of each other: a merchant order number already submitted for cashin can still be submitted for cashout; an order number only needs to be unique within the same business direction.