Decode PIX QR Code

Decode a PIX QR Code payload.

Endpoint

POST /cashin/pix/decode-qrcode

Authentication

Merchant Credential. See Authentication.

Background

Decodes the code value string of a Pix payment QR code to obtain the QR code type, amount, whether the amount can be modified, and the payee account information. The API only performs decoding: it does not create cashin or cashout orders and does not initiate any deduction. A successful decode does not mean the payment has been made or that the payment will definitely succeed.

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.
X-Nonce	Header	string	64	Yes	Random string for request anti-replay protection.
Digest	Header	string	52	Yes	Digest computed over the request body actually sent. Format: SHA-256=<Base64Digest>.
Authorization	Header	string	Variable	Yes	ES256 request signature, where keyId is the merchant key version.
qrcode	Body	string	Up to 16384 bytes	Yes	Complete Pix Copy and Paste code value; must not be empty or contain only whitespace. Pass the QR code text, not an image, an image URL, or a Base64 image.
payDate	Body	string	10	No	Payment date in YYYY-MM-DD format, for example 2026-09-07; must be a valid calendar date. If omitted or passed as an empty string, no payment date is specified.

Request Example

POST /cashin/pix/decode-qrcode HTTP/1.1
Content-Type: application/json
X-Merchant-Id: 92315566000120
X-Timestamp: 1788768000
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:

{
  "qrcode": "00020126580014br.gov.bcb.pix01361234567890123456789012345678901234520400005303986540550.005802BR5925Example Company Name6014CIDADE EXEMPLO62070503***63045ABC",
  "payDate": "2026-09-07"
}

Response Fields

The API uses a unified status, msg, data response structure. The decoded fields in the table below are based on a successful response; when the request fails, any returned data must not be used as a valid decode result.

Field	Type	Description
status	int	Response code
msg	string	Corresponds to status
data	object	Decode result; may be absent when the request fails at the authentication or protocol parsing stage.
data.type	string	QR code type; see the table below.
data.amount	decimal or null	QR code amount in BRL; null when no amount information is provided.
data.allowsChangeAmount	boolean or null	Whether the amount can be modified; true means allowed, false means not allowed, and null means not provided.
data.toPix	string	Payee Pix Key; empty string when not provided.
data.toPixType	string	Payee Pix Key type; empty string when not provided.
data.toIspb	string	ISPB code of the receiving institution; handled as a string to preserve leading zeros, empty string when not provided.
data.toName	string	Payee name; empty string when not provided.
data.toCpfCnpj	string	Payee CPF or CNPJ; may be masked, empty string when not provided.
data.agency	string	Payee bank branch number; empty string when not provided.
data.toAccount	string	Payee account number; empty string when not provided.

QR Code Types and Amount

type	Meaning
STATIC	Static QR code
DYNAMIC_IMMEDIATE	Dynamic QR code for immediate payment
DYNAMIC_CHARGE	Dynamic QR code for bills

When amount or allowsChangeAmount is null, it must not be treated as a zero amount or as an amount that can be modified. If a type outside the list above is returned, amount and allowsChangeAmount are null; handle it as an unrecognized type.

Response Example

The following is an illustrative response for a static QR code; all account and identity information is sample data.

{
  "status": 200,
  "msg": "sucesso",
  "data": {
    "type": "STATIC",
    "amount": 50.00,
    "allowsChangeAmount": false,
    "toPix": "receiver@example.com",
    "toPixType": "EMAIL",
    "toIspb": "01234567",
    "toName": "Example Receiver",
    "toCpfCnpj": "123******01",
    "agency": "0001",
    "toAccount": "123456"
  }
}