Decode a scanned PIX QR code

curl --request POST \
  --url https://api.example.com/v1/qrcodes/decode \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "qrCode": "00020126...",
  "accountId": "019a1b2c-3d4e-7f60-8a9b-0c1d2e3f4a5b",
  "indirectId": "3f2504e0-4f89-41d3-9a0c-0305e82c3301",
  "ispb": "12345678"
}
'

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/v1/qrcodes/decode"

	payload := strings.NewReader("{\n  \"qrCode\": \"00020126...\",\n  \"accountId\": \"019a1b2c-3d4e-7f60-8a9b-0c1d2e3f4a5b\",\n  \"indirectId\": \"3f2504e0-4f89-41d3-9a0c-0305e82c3301\",\n  \"ispb\": \"12345678\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    qrCode: '00020126...',
    accountId: '019a1b2c-3d4e-7f60-8a9b-0c1d2e3f4a5b',
    indirectId: '3f2504e0-4f89-41d3-9a0c-0305e82c3301',
    ispb: '12345678'
  })
};

fetch('https://api.example.com/v1/qrcodes/decode', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.example.com/v1/qrcodes/decode"

payload = {
    "qrCode": "00020126...",
    "accountId": "019a1b2c-3d4e-7f60-8a9b-0c1d2e3f4a5b",
    "indirectId": "3f2504e0-4f89-41d3-9a0c-0305e82c3301",
    "ispb": "12345678"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "amount": 10050,
  "payee": {
    "accountType": 0,
    "keyType": 2,
    "accountDigit": "7",
    "accountNumber": "123456",
    "branch": "0001",
    "document": "12345678909",
    "ispb": "12345678",
    "name": "Jane Doe"
  },
  "qrCodeType": "DYNAMIC",
  "amountTroco": 0,
  "city": "Sao Paulo",
  "createdAt": "2020-01-20T12:29:15.043Z",
  "description": "Invoice 42",
  "dueDate": "2026-12-31",
  "endToEndId": "E1234567890",
  "isPixSaque": false,
  "isPixTroco": false,
  "ispbPss": "00360305",
  "key": "recipient@bank.com",
  "presentedAt": "2020-01-23T10:21:34.107Z",
  "revision": 0,
  "txId": "TX001"
}

{
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

Decode a scanned PIX QR code

Decodes a scanned PIX QR-code payload, normalizing static / immediate-dynamic / cobv sub-types into one null-safe response. The payer document is sourced from accountId’s CRM alias for the JDPI decode header (PI-PayerId).

Which of this deployment’s direct participants acts is decided by ispb, by exactly the rule an order’s payerIspb follows: this deployment may act as several direct participants, each with its own customers and its own JDPI credential, and naming none is answerable only while there is one answer. Omit it while this deployment acts as a single participant; once it acts as several, omitting it is 422 PIX-0127 and naming one it is not is 422 PIX-0128. When the account named on the request cannot be used by that participant, the request is refused before the operation acts and the answer names the account: 422 PIX-0137 when it is held in a ledger that is not configured for Pix, 422 PIX-0138 when its record does not say which ledger holds it, and 422 PIX-0139 when its record names a different institution. It selects the JDPI credential the decode goes out on and nothing else.

Paying through an INDIRECT participant: send indirectId, the same one the payment order will carry, and the payer’s CPF/CNPJ in X-Payer-Document. The plugin then generates the endToEndId under that indirect’s ISPB - the institution the payment originates from - and sends it to JD on the decode (PI-EndToEndId); the response returns it and the order must carry it unchanged.

POST

qrcodes

decode

Decode a scanned PIX QR code

curl --request POST \
  --url https://api.example.com/v1/qrcodes/decode \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "qrCode": "00020126...",
  "accountId": "019a1b2c-3d4e-7f60-8a9b-0c1d2e3f4a5b",
  "indirectId": "3f2504e0-4f89-41d3-9a0c-0305e82c3301",
  "ispb": "12345678"
}
'

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/v1/qrcodes/decode"

	payload := strings.NewReader("{\n  \"qrCode\": \"00020126...\",\n  \"accountId\": \"019a1b2c-3d4e-7f60-8a9b-0c1d2e3f4a5b\",\n  \"indirectId\": \"3f2504e0-4f89-41d3-9a0c-0305e82c3301\",\n  \"ispb\": \"12345678\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    qrCode: '00020126...',
    accountId: '019a1b2c-3d4e-7f60-8a9b-0c1d2e3f4a5b',
    indirectId: '3f2504e0-4f89-41d3-9a0c-0305e82c3301',
    ispb: '12345678'
  })
};

fetch('https://api.example.com/v1/qrcodes/decode', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.example.com/v1/qrcodes/decode"

payload = {
    "qrCode": "00020126...",
    "accountId": "019a1b2c-3d4e-7f60-8a9b-0c1d2e3f4a5b",
    "indirectId": "3f2504e0-4f89-41d3-9a0c-0305e82c3301",
    "ispb": "12345678"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "amount": 10050,
  "payee": {
    "accountType": 0,
    "keyType": 2,
    "accountDigit": "7",
    "accountNumber": "123456",
    "branch": "0001",
    "document": "12345678909",
    "ispb": "12345678",
    "name": "Jane Doe"
  },
  "qrCodeType": "DYNAMIC",
  "amountTroco": 0,
  "city": "Sao Paulo",
  "createdAt": "2020-01-20T12:29:15.043Z",
  "description": "Invoice 42",
  "dueDate": "2026-12-31",
  "endToEndId": "E1234567890",
  "isPixSaque": false,
  "isPixTroco": false,
  "ispbPss": "00360305",
  "key": "recipient@bank.com",
  "presentedAt": "2020-01-23T10:21:34.107Z",
  "revision": 0,
  "txId": "TX001"
}

{
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

Autorizaciones

Authorization

string

header

requerido

JWT bearer token issued by the identity provider.

Encabezados

X-Payer-Document

string

The CPF/CNPJ of the indirect participant's customer who scans and pays, as the indirect declares it, mask allowed. Only with indirectId, and required there unless the legacy accountId is sent instead: an indirect keeps its customers in its own core, so this plugin reads no record of them and sends this document to JD as the payer (PI-PayerId), canonical (digits, and the letters of an alphanumeric CNPJ). Refused 400 PIX-0061 without indirectId, together with accountId, or when it is not a CPF of 11 digits or a CNPJ of 14 characters.

Ejemplo:

"52998224725"

Cuerpo

application/json

qrCode

string

requerido

The scanned EMV QR-code payload to decode.

Ejemplo:

"00020126..."

accountId

string

The Midaz ledger account id of the scanning payer, a customer of the asking direct participant (sources the PI-PayerId document). REQUIRED on a direct decode (absent or blank is 400 PIX-0061). With indirectId it is DEPRECATED in favour of the X-Payer-Document header: an indirect keeps its customers in its own core. accountId is still accepted there, unchanged, when the direct participant's own credential sends the request, and refused 400 PIX-0061 when an Access Manager partner is behind the request. Sending it together with X-Payer-Document is 400 PIX-0061.

Ejemplo:

"019a1b2c-3d4e-7f60-8a9b-0c1d2e3f4a5b"

indirectId

string<uuid>

Optional identifier (UUID) of the indirect participant the scanning payer pays through - send the SAME indirectId the payment order will carry. The plugin then generates the endToEndId under that indirect's ISPB, the institution the payment originates from, and sends it to JD on the decode; the response returns it, and the order must carry it unchanged. Without it JD generates the endToEndId under the direct participant's ISPB. Omit it for a payment the direct participant pays. Validated before JD is called, exactly as the order validates it: 404 PIX-0095 unknown to this tenant, 422 PIX-0100 not ACTIVE, 422 PIX-0111 while this deployment's indirect-participants feature is off. The decode then acts as the direct participant the indirect is mounted on: omit ispb, or send that participant's ISPB; any other is 422 PIX-0102. A token confined to one indirect has to name it here.

Ejemplo:

"3f2504e0-4f89-41d3-9a0c-0305e82c3301"

ispb

string

The ISPB of the direct participant this decode asks as. This deployment may act as SEVERAL direct SPI participants - one ISPB each, each with its own customers and its own JDPI credential - and this field is the only thing on the request that says which of them acts. OPTIONAL while it acts as a single participant: omit it and that one acts. REQUIRED once it acts as several - omitted is 422 PIX-0127, and an ISPB this deployment does not act as is 422 PIX-0128. It is ROUTING DATA you supply and guarantee, exactly like payerIspb on a transaction: never a credential, never read from a header or a path, and it never widens what your token can reach. It selects the JDPI credential the decode goes out on and nothing else - the decoded charge belongs to the payee, not to you. Send it as an absent key, not an empty string; an empty value is refused 400 PIX-0061.

Pattern: ^[0-9A-Z]{8}$

Ejemplo:

"12345678"

Respuesta

amount

integer<int64>

requerido

The decoded amount in centavos.

Ejemplo:

10050

payee

object

requerido

The decoded recipient identity.

Show child attributes

qrCodeType

string

requerido

The decoded QR type (STATIC or DYNAMIC; cobv folds onto DYNAMIC).

Ejemplo:

"DYNAMIC"

amountTroco

integer<int64>

The Pix Troco amount in centavos (troco only).

Ejemplo:

0

city

string

Recipient city (cidade; §8.3.3 Obrg=Sim on every block).

Ejemplo:

"Sao Paulo"

createdAt

string

When the dynamic charge was created (§8.3.3 Obrg=Sim).

Ejemplo:

"2020-01-20T12:29:15.043Z"

description

string

Additional data (dadosAdicionais).

Ejemplo:

"Invoice 42"

dueDate

string

Due date (cobv/static optional).

Ejemplo:

"2026-12-31"

endToEndId

string

The SPI end-to-end id.

Ejemplo:

"E1234567890"

isPixSaque

boolean

Whether the QR carries a Pix Saque leg.

Ejemplo:

false

isPixTroco

boolean

Whether the QR carries a Pix Troco leg.

Ejemplo:

false

ispbPss

string

The saque/troco PSS participant ISPB (a v5.5.0 string; leading zeros are significant).

Ejemplo:

"00360305"

key

string

The recipient PIX key.

Ejemplo:

"recipient@bank.com"

presentedAt

string

When the payer captured the QR, i.e. the moment of this decode (dtHrApresentacao; §8.3.3 Obrg=Sim).

Ejemplo:

"2020-01-23T10:21:34.107Z"

revision

integer<int64>

Charge revision counter (revisao). Always present on a DYNAMIC decode, including at its initial value 0; absent on a STATIC one, whose §8.3.3 block declares no revisao.

Ejemplo:

0

txId

string

Conciliation id (idConciliacaoRecebedor), to copy verbatim into POST /v1/transactions. A STATIC QR may carry a txId JDPI §8.4.1 refuses on the payment (any character outside [a-zA-Z0-9], e.g. TX-001); POST /v1/transactions refuses such a txId 400 PIX-0061.

Ejemplo:

"TX001"

APIs del participante directo

APIs de participantes indirectos

Decode a scanned PIX QR code

Autorizaciones

Encabezados

Cuerpo

Respuesta