Generate BR Code

Prerequisite: for a dynamic QR, the cob/cobv charge must be created first (see putCob, putCobV) — the payload links to it by txid/locator. Generates a new BR Code (QR code) payload following the EMV QRCPS-MPM standard.

POST /api/v1/brcode/

Generate BR Code

cURL

curl --request POST \
  --url https://spi.sandbox.lerian.net/api/v1/brcode/ \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Idempotency: <x-idempotency>' \
  --data '
{
  "kind": "STATIC",
  "merchantCity": "São Paulo",
  "merchantName": "Lerian Studio",
  "pixKey": "12345678901",
  "amount": "100.00",
  "arrangementType": "direct_participant",
  "fss": "12345678",
  "infoAdicional": "Compra 042",
  "merchantCategoryCode": "0000",
  "txId": "Compra042"
}
'

201

{
  "createdAt": "2025-03-07T14:30:00Z",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "kind": "STATIC",
  "merchantCity": "São Paulo",
  "merchantName": "Lerian Studio",
  "pixKey": "12345678901",
  "status": "ACTIVE",
  "updatedAt": "2025-03-07T14:30:00Z",
  "amount": "100.00",
  "copyPaste": "00020126580014br.gov.bcb.pix...",
  "fss": "12345678",
  "ignoredAmount": "10.00",
  "ignoredFss": "12345678",
  "ignoredInfoAdicional": "Compra 042",
  "ignoredTxId": "TXIDABCDEFGHIJKLMNOPQRSTUVWXYZ",
  "infoAdicional": "Compra 042",
  "payloadUrl": "pix.example.com/qr/v2/550e8400",
  "qrPngBase64": "iVBORw0KGgoAAAANSUhEUgAA...",
  "qrPngContentType": "image/png",
  "raw": "00020126580014br.gov.bcb.pix...",
  "recurrenceUrl": "pix.example.com/rec/2353c790eefb11eaadc10242ac120002",
  "txId": "Compra042"
}

Authorizations

Authorization · string · header · required

JWT bearer token issued by the identity provider.

Headers

X-Idempotency · string · required

Idempotency key, max 255 characters

Body

application/json

kind · string · required

BR Code kind: STATIC (reusable, no expiry) or DYNAMIC (single-use, resolved via payload URL). Empty defaults to STATIC.

Example:

"STATIC"

merchantCity · string · required

Merchant city encoded into the EMV payload (EMV field 60). At most 15 characters, rejected rather than truncated, same as merchantName.

Required string length: 1 - 15

Example:

"São Paulo"

merchantName · string · required

Merchant legal/trade name encoded into the EMV payload (EMV field 59). At most 25 characters: the encoder rejects a longer name rather than truncating it, so a caller sourcing the identity from a longer field must shorten it first.

Required string length: 1 - 25

Example:

"Lerian Studio"

pixKey · string · required

Pix key identifying the receiver (CPF/CNPJ, phone, email, or random EVP key). At most 77 characters. The service checks the shape of each key type (CPF and CNPJ check digits, a lower-case e-mail address, +55 plus a valid Brazilian area code, a version-4 UUID). Beside a withdrawal facilitator (fss), the key shares the merchant account template and its limit drops to 65 characters.

Required string length: 1 - 77

Example:

"12345678901"

amount · string

Transaction amount in BRL as a decimal string, scale 2 (e.g. "100.00"). Empty leaves the amount open for the payer to set.

Example:

"100.00"

arrangementType · string

Pix arrangement type governing MCC/key/amount constraints (e.g. direct_participant). Empty applies the default arrangement.

Example:

"direct_participant"

fss · string

Eight-digit ISPB of the withdrawal service facilitator (EMV subfield 26-03). Its presence marks the code as a Pix Saque QR; static codes only, and empty to omit it.

Example:

"12345678"

infoAdicional · string

Free text shown to the payer while tracking the QR (EMV subfield 26-02). Shares the merchant account template's 99 characters with the Pix key and fss, so the accepted length depends on those; empty to omit it.

Example:

"Compra 042"

merchantCategoryCode · string

ISO 18245 four-digit Merchant Category Code; 0000 indicates no specific category.

Example:

"0000"

txId · string

Reference label written into EMV 62-05: at most 25 characters of a-z, A-Z or 0-9. It is the static code's own conciliation label, NOT the 26..35-character txid of an API-created cobrança. Empty for static codes that omit a transaction reference.

Example:

"Compra042"

Response

201

application/json

Created

createdAt · string · required

Creation timestamp in RFC3339 UTC.

Example:

"2025-03-07T14:30:00Z"

id · string · required

Server-assigned payload identifier (UUID).

Example:

"550e8400-e29b-41d4-a716-446655440000"

kind · string · required

BR Code kind: STATIC (reusable) or DYNAMIC (single-use).

Example:

"STATIC"

merchantCity · string · required

Merchant city from the EMV payload (EMV field 60).

Example:

"São Paulo"

merchantName · string · required

Merchant legal/trade name from the EMV payload (EMV field 59).

Example:

"Lerian Studio"

pixKey · string · required

Pix key identifying the receiver (CPF/CNPJ, phone, email, or random EVP key).

Example:

"12345678901"

status · string · required

Lifecycle status of the payload (e.g. ACTIVE).

Example:

"ACTIVE"

updatedAt · string · required

Last-update timestamp in RFC3339 UTC.

Example:

"2025-03-07T14:30:00Z"

amount · string

Transaction amount in BRL as a decimal string, scale 2 (empty when the amount is open).

Example:

"100.00"

copyPaste · string

Pix copy-and-paste string (the raw EMV payload); empty when unavailable.

Example:

"00020126580014br.gov.bcb.pix..."

fss · string

Eight-digit ISPB of the withdrawal service facilitator (EMV subfield 26-03), and the Pix Saque marker: its presence means this IS a Pix Saque QR. Populated on static codes only; a dynamic code's merchant account template is GUI plus URL, so a 26-03 there marks nothing and is reported as ignoredFss instead, a dynamic withdrawal or troco being declared in the URL-resolved payload's retirada object. Empty when the code omits it.

Example:

"12345678"

ignoredAmount · string

Amount a non-conformant emitter wrote into EMV 54 of a dynamic code. A dynamic code's amount comes from the payload URL, so this value must NOT be paid or displayed as owed; it is reported only to diagnose the emitter. Empty otherwise.

Example:

"10.00"

ignoredFss · string

Value a non-conformant emitter wrote into EMV subfield 26-03 of a dynamic code, whose merchant account template is GUI plus URL alone. Like ignoredAmount it must NOT be acted on: it is NOT a Pix Saque marker and is not even guaranteed to be a valid eight-digit ISPB, since a dynamic 26-03 is neither shape-checked nor charged to the template's character budget. Reported only to diagnose the emitter. Empty otherwise.

Example:

"12345678"

ignoredInfoAdicional · string

Free text a non-conformant emitter wrote into EMV subfield 26-02 of a dynamic code, whose merchant account template is GUI plus URL alone. It must NOT be displayed as the code's own text: a dynamic charge's real infoAdicionais come from the URL-resolved payload, and this value is neither length-checked nor charged to the template's character budget. Reported only to diagnose the emitter. Empty otherwise.

Example:

"Compra 042"

ignoredTxId · string

Reference label a non-conformant emitter wrote into EMV 62-05 of a dynamic code. Like ignoredAmount it must NOT be acted on: the URL-resolved payload prevails. Empty otherwise.

Example:

"TXIDABCDEFGHIJKLMNOPQRSTUVWXYZ"

infoAdicional · string

Free text the payer is shown while tracking the code (EMV subfield 26-02), and the code's own display text. Populated on static codes only; a dynamic code's merchant account template is GUI plus URL, so text there is emitter noise and is reported as ignoredInfoAdicional instead, a dynamic charge's real infoAdicionais living in the URL-resolved payload. Empty when the code omits it.

Example:

"Compra 042"

payloadUrl · string

Payload location for dynamic codes, without protocol prefix; resolvable over HTTPS only. Empty for static codes.

Example:

"pix.example.com/qr/v2/550e8400"

qrPngBase64 · string

QR code image rendered from the raw payload, base64-encoded PNG (only populated on generation responses).

Example:

"iVBORw0KGgoAAAANSUhEUgAA..."

qrPngContentType · string

MIME content type of qrPngBase64 (image/png) when an image is present.

Example:

"image/png"

raw · string

Raw EMV BR Code string; same value as copyPaste, retained for compatibility.

Example:

"00020126580014br.gov.bcb.pix..."

recurrenceUrl · string

Recurrence-parameters location of a composite BR Code (EMV subfield 80-25), without protocol prefix; resolvable over HTTPS only. Its presence means this code initiates a Pix Automático recurrence, and it may stand alongside a pixKey or a payloadUrl or, in the recurrence-only configuration, alone. Empty on a code that initiates no recurrence.

Example:

"pix.example.com/rec/2353c790eefb11eaadc10242ac120002"

txId · string

Reference label carried in EMV 62-05, at most 25 characters of a-z, A-Z or 0-9; empty when not present.

Example:

"Compra042"