/cashin/pix/decode-qrcode-partner Decode PIX QR Code

Background

Parses 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 receiver's account information. The API only performs decoding; it does not create a payment or payout order and does not initiate any debit. A successful decode does not mean the payment has been made or will definitely succeed.

Endpoint

Item	Value
Method	POST
Path	/cashin/pix/decode-qrcode-partner
Content-Type	application/json
Purpose	Decode a PIX payment QR code

Access Requirements

• Common specifications
• Request Signing

Authentication uses the partner's primary merchant ID and its corresponding credentials. This API does not require a merchant order number or subMerchantNo.

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.
X-Nonce	Header	string	64	Yes	Anti-replay random string for the request.
Digest	Header	string	52	Yes	Digest computed over the request body actually sent, in the format SHA-256=<Base64 digest>.
Authorization	Header	string	Variable	Yes	ES256 request signature information, where keyId is the partner key version.
qrcode	Body	string	Up to 16384 bytes	Yes	The complete PIX Copy and Paste code value; must not be empty or contain only whitespace. Pass the QR code text, not an image, image URL, or image Base64.
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-partner HTTP/1.1
Content-Type: application/json
X-Merchant-Id: 92315566000120
X-Timestamp: 1788768000
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:

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

Response Fields

The API uses the standard status, msg, and data response structure. The decoded fields in the table below are valid only in a success response; if the request fails, any returned data must not be used as a valid decode result.

Field	Type	Description
status	int	Response code
msg	string	Message corresponding to status
data	object	Decode result; may be omitted 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	Receiver's Pix key; empty string when not provided.
data.toPixType	string	Receiver's Pix key type; empty string when not provided.
data.toIspb	string	ISPB code of the receiving institution; treated as a string to preserve leading zeros, empty string when not provided.
data.toName	string	Receiver's name; empty string when not provided.
data.toCpfCnpj	string	Receiver's CPF or CNPJ; may be masked, empty string when not provided.
data.agency	string	Receiving bank branch number; empty string when not provided.
data.toAccount	string	Receiving 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, do not interpret it as a zero amount or as allowing amount changes. If the returned type is not in the list above, amount and allowsChangeAmount are null; treat 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": 125.50,
    "allowsChangeAmount": false,
    "toPix": "receiver@example.com",
    "toPixType": "EMAIL",
    "toIspb": "01234567",
    "toName": "Example Receiver",
    "toCpfCnpj": "123******01",
    "agency": "0001",
    "toAccount": "123456"
  }
}

Failure Handling

• If qrcode is missing, blank, or exceeds the length limit, or payDate is not a valid date, correct the request and call again.
• When decoding fails or the result is invalid, the API returns a failure response; do not continue the payment using empty fields from a failure response.
• For specific failure codes, refer to Response Status and the actual response.

Related APIs

• Create payment QR code
• Query payment order (merchant order number / e2eId)