Create Payment / QR Code

Create a PIX payment order and obtain a QR Code payload.

Endpoint

POST /cashin/pix/create-qrcode

Authentication

Merchant Credential. See Authentication.

Background

This API creates a Brazilian Pix dynamic QR code payment order. The merchant submits its own order and the payment amount; after Adopay completes request signature verification, parameter validation, and idempotency checks, it creates the cashin order and returns the Pix QR code string.

The merchant must ensure that the merchant order number is unique within the scope of the same merchant's cashin orders. The merchant order number serves as the idempotency key, with an idempotency validity period of 3 months: within this period, resubmitting the same order number will not create a duplicate cashin order. Idempotency for cashin and cashout does not exclude each other; an order number submitted for cashin may be reused in cashout. A successful synchronous response only means the QR code was created and the order has entered the pending-payment state; the final payment result is determined by the asynchronous notification or the Query Payment by Order SN result.

QR Code Order Transaction Flow

• Synchronous ordering phase: The user submits an order, the merchant requests QR code creation from Adopay, and displays the returned QR code or the payment code to the user.
• Asynchronous payment phase: The user completes the Pix payment through the paying bank, the central bank BCB notifies Adopay of the payment result, and Adopay notifies the merchant after updating the order.

sequenceDiagram
    autonumber
    actor U as User
    participant M as Merchant
    participant A as Adopay
    participant PB as Paying Bank
    participant BCB as Central Bank BCB
    U->>M: Submit order
    M->>A: POST /cashin/pix/create-qrcode
    A->>A: Verify signature, validate parameters and idempotency, create order and QR code
    A-->>M: Return platOrderNo, qrcode, expireTime
    M-->>U: Display QR code or payment code
    U->>PB: Scan the QR code or paste the payment code and confirm payment
    PB->>BCB: Submit Pix payment
    BCB-->>A: Notify payment result
    A->>A: Verify the result and update the order status
    A-->>M: POST the payment result to notifyUrl
    alt Merchant confirms successfully
        M-->>A: Return success confirmation
        M-->>U: Update the order and display the payment result
    else Merchant does not confirm successfully
        A-->>M: Retry according to the notification task policy
    end

Request Fields

Field	Location	Type	Length	Required	Description
X-Merchant-Id	Header	string	64	Yes	Merchant ID, read from the request header.
X-Timestamp	Header	int	19	Yes	Unix request timestamp in seconds; used for request freshness validation.
X-Nonce	Header	string	64	Yes	Random string for request anti-replay protection.
Digest	Header	string	52	Yes	Digest of the request body. Format: SHA-256=<Base64Digest>.
Authorization	Header	string	-	Yes	ES256 request signature, where keyId is the merchant key version.
merchantOrderNo	Body	string	64	Yes	Merchant order number; unique among the same merchant's cashin orders. Cashin and cashout idempotency are not mutually exclusive; the same order number may be reused in cashout.
expireTime	Body	int	19	No	Order expiration deadline, Unix timestamp in seconds; the value must be 1 minute to 24 hours after the current time. Defaults to 30 minutes if not provided.
mustPayerTaxNo	Body	string	64	No	Tax ID that the payer must match; the credit should be rejected if the actual payer's tax ID does not match.
amount	Body	decimal(25,2)	25,2	Yes	Payment amount in BRL; must be greater than 0, with at most two decimal places.
notifyUrl	Body	string	255	No	URL where the merchant receives payment result notifications. The submitted value takes precedence; otherwise the merchant-configured URL is used.
attach	Body	string	128	No	Opaque data passed through by the merchant; returned as-is in callback notifications or order queries, invisible to the paying user.
reference	Body	string	128	No	Description visible in the user's bank statement details, up to 128 characters.

Request Examples

Request header example:

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=<Base64Digest>
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.5,
  "notifyUrl": "https://merchant.example.com/notify/pix",
  "attach": "order-source=checkout",
  "reference": "Compra de produtos"
}

Response Fields

The API uses a unified status, msg, data response structure. A status of 200 means the dynamic QR code was created successfully; any other value means the request processing failed or the order is still being processed.

Field	Type	Length	Returned	Description
status	int	4	Yes	Response code
msg	string	128	Yes	Corresponds to status
data	object	N/A	No	Pre-order response data; may be absent when the request fails before entering business processing.
data.merchantNo	string	64	Conditional	Merchant ID; returned after pre-order business processing starts.
data.merchantOrderNo	string	64	Conditional	Merchant order number; returned after pre-order business processing starts.
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 used to generate a QR code or for copy-and-pay payment.

Response Examples

Success response example:

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