Decode QR Code

Decodes a QR Code from a base64 image or EMV BR Code payload string. Returns structured information including QR Code type (STATIC/DYNAMIC), PIX key, amount, merchant info, txid, and location URL. Automatically detects if input is a base64 image or EMV payload (starting with '0002'). For dynamic QR Codes, resolves the location URL to fetch charge details. Requires Idempotency-Key header; payerDocument is provided in the request body and is forwarded to the keys service when resolving the PIX key for static QR Codes.

Headers

Idempotency-Key
Type: string
required

Unique idempotency key

Body·

required

application/json

Request to decode a QR Code from base64 image or EMV payload

payerDocument
Type: string
min length:
1
required

Payer document (CPF or CNPJ digits only); forwarded to keys API on static QR key lookup.
qrCode
Type: string
min length:
1
required

QR Code image in base64 format (with or without data URI prefix).
municipalityCode
Type: string

IBGE municipality code of the payer (7 digits); forwarded on COBV location fetch.
paymentDate
Type: string Format: date

Intended payment date (DPP). For dynamic COBV, forwarded to the receiver when fetching the location URL so the final amount reflects discounts/interest/fines on that date.

Responses

application/json

Código interno	HTTP	Descrição	Erro normativo Bacen
`CHARGE-0004`	400	QRCode invalid format	—
`CHARGE-0012`	400	Failed to decode QR Code	—
`CHARGE-0017`	400	Charge has expired	`CobOperacaoInvalida`
`CHARGE-0019`	400	PSP service is unavailable	`ServicoIndisponivel`
`CHARGE-0020`	400	Invalid location URL	`PayloadLocationOperacaoInvalida`
`CHARGE-0021`	400	Charge is not in a valid status for this operation	`CobOperacaoInvalida`

application/json

application/json

Código interno	HTTP	Descrição	Erro normativo Bacen
`CHARGE-0001`	404	Invalid Pix key: key not found or inactive	`CobOperacaoInvalida`
`CHARGE-0018`	404	Charge not found	`CobNaoEncontrado`

application/json

application/json
application/json
application/json

Código interno	HTTP	Descrição	Erro normativo Bacen
`CHARGE-0005`	502	Error validating Pix key	`ServicoIndisponivel`

post/api/v1/charges/decode

curl http://localhost/api/v1/charges/decode \
  --request POST \
  --header 'Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --data '{
  "qrCode": "",
  "payerDocument": "",
  "paymentDate": "",
  "municipalityCode": ""
}'

Show Schema

{
  "type": "STATIC",
  "emv": "string",
  "key": "string",
  "value": "string",
  "cashWithdrawal": {
    "type": "SAQUE",
    "cashAmount": "string",
    "changeMode": 1,
    "agentModality": "AGTEC",
    "cashierIspb": "string"
  },
  "merchant": {
    "name": "string",
    "city": "string",
    "taxId": "string"
  },
  "txid": "string",
  "locationUrl": "string",
  "additionalInfo": "string",
  "status": "ACTIVE",
  "revision": 1,
  "calendar": {
    "createdAt": "2026-09-16T19:14:18.660Z",
    "expiresAt": "2026-09-16T19:14:18.660Z",
    "expiration": 1,
    "dueDate": "2026-09-16"
  },
  "debtor": {
    "cpf": "string",
    "cnpj": "string",
    "name": "string"
  },
  "receiver": {
    "taxId": "string",
    "name": "string",
    "tradeName": "string",
    "uf": "string",
    "accountIspb": "string",
    "accountType": "string",
    "accountBranch": "string",
    "accountNumber": "string"
  },
  "additionalInfoList": [
    {
      "name": "string",
      "value": "string"
    }
  ],
  "cobvFinalAmountBreakdown": {
    "paymentDate": "string",
    "municipalityCode": "string",
    "originalValue": "string",
    "appliedRebate": "string",
    "appliedDiscount": "string",
    "appliedInterest": "string",
    "appliedFine": "string",
    "finalValue": "string"
  },
  "ispb": "string",
  "endToEndId": "string",
  "recurrence": {
    "recurrenceId": "string",
    "contract": "string",
    "object": "string",
    "debtorName": "string",
    "debtorCpf": "string",
    "debtorCnpj": "string",
    "startDate": "string",
    "endDate": "string",
    "periodicity": "string",
    "value": "string",
    "receiverMinimumValue": "string",
    "receiverCnpj": "string",
    "receiverName": "string",
    "receiverIspb": "string",
    "retryPolicy": "string",
    "status": "string"
  }
}

QR Code decoded successfully