> ## Documentation Index > Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt > Use this file to discover all available pages before exploring further. # 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. ## OpenAPI ````yaml /pt/openapi/v3-current/spi-brcode.yaml post /api/v1/brcode/ openapi: 3.1.0 info: contact: email: contact@lerian.studio name: Lerian Studio url: https://lerian.studio description: BR Code service for QR code generation and decoding (EMV QRCPS-MPM). license: name: Lerian Studio General License title: Lerian SPI — BR Code API version: 1.0.0 servers: - url: https://api.example.com description: >- Replace the example host with the URL provided during environment onboarding. security: [] tags: - description: EMV BR Code payload generation, decoding, validation, info, and lookup. name: BRCode - description: >- Pix charges (Cob/CobV/LoteCobV): create, retrieve by TxID, list, cancel, reconcile, and resolve public payloads. name: Charges - description: >- Flow (mandatory order): create cob/cobv → generate QR/payload. A dynamic BR Code payload references a charge, so the cob/cobv charge MUST be created first; the payload links to it by txid/locator. name: charge paths: /api/v1/brcode/: post: tags: - BRCode - charge summary: Generate BR Code description: >- 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. operationId: generateBRCode parameters: - description: Idempotency key, max 255 characters in: header name: X-Idempotency required: true schema: description: Idempotency key, max 255 characters type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/GenerateBRCodeRequest' required: true responses: '201': content: application/json: schema: $ref: '#/components/schemas/PayloadResponse' description: Created links: prerequisite: description: >- Charge prerequisite: for a dynamic QR the cob/cobv charge (putCob, putCobV) must exist before the payload references it. operationId: putCob '422': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Unprocessable Entity '500': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Internal Server Error default: content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Error security: - BearerAuth: [] components: schemas: GenerateBRCodeRequest: additionalProperties: false properties: amount: description: >- Transaction amount in BRL as a decimal string, scale 2 (e.g. "100.00"). Empty leaves the amount open for the payer to set. examples: - '100.00' type: string arrangementType: description: >- Pix arrangement type governing MCC/key/amount constraints (e.g. direct_participant). Empty applies the default arrangement. examples: - direct_participant type: string fss: description: >- Eight-character ISPB ([0-9A-Z]{8}) 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. examples: - '12345678' type: string infoAdicional: description: >- 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. examples: - Compra 042 type: string kind: description: >- BR Code kind: STATIC (reusable, no expiry) or DYNAMIC (single-use, resolved via payload URL). Empty defaults to STATIC. examples: - STATIC type: string merchantCategoryCode: description: >- ISO 18245 four-digit Merchant Category Code; 0000 indicates no specific category. examples: - '0000' type: string merchantCity: description: >- Merchant city encoded into the EMV payload (EMV field 60). At most 15 characters, rejected rather than truncated, same as merchantName. examples: - São Paulo maxLength: 15 minLength: 1 type: string merchantName: description: >- 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. examples: - Lerian Studio maxLength: 25 minLength: 1 type: string pixKey: description: >- 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. examples: - '12345678901' maxLength: 77 minLength: 1 type: string txId: description: >- 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. examples: - Compra042 type: string required: - kind - merchantName - merchantCity - pixKey type: object PayloadResponse: additionalProperties: false properties: amount: description: >- Transaction amount in BRL as a decimal string, scale 2 (empty when the amount is open). examples: - '100.00' type: string copyPaste: description: >- Pix copy-and-paste string (the raw EMV payload); empty when unavailable. examples: - 00020126580014br.gov.bcb.pix... type: string createdAt: description: Creation timestamp in RFC3339 UTC. examples: - '2025-03-07T14:30:00Z' type: string fss: description: >- Eight-character ISPB ([0-9A-Z]{8}) 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. examples: - '12345678' type: string id: description: Server-assigned payload identifier (UUID). examples: - 550e8400-e29b-41d4-a716-446655440000 type: string ignoredAmount: description: >- 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. examples: - '10.00' type: string ignoredFss: description: >- 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-character 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. examples: - '12345678' type: string ignoredInfoAdicional: description: >- 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. examples: - Compra 042 type: string ignoredTxId: description: >- 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. examples: - TXIDABCDEFGHIJKLMNOPQRSTUVWXYZ type: string infoAdicional: description: >- 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. examples: - Compra 042 type: string kind: description: 'BR Code kind: STATIC (reusable) or DYNAMIC (single-use).' examples: - STATIC type: string merchantCity: description: Merchant city from the EMV payload (EMV field 60). examples: - São Paulo type: string merchantName: description: Merchant legal/trade name from the EMV payload (EMV field 59). examples: - Lerian Studio type: string payloadUrl: description: >- Payload location for dynamic codes, without protocol prefix; resolvable over HTTPS only. Empty for static codes. examples: - pix.example.com/qr/v2/550e8400 type: string pixKey: description: >- Pix key identifying the receiver (CPF/CNPJ, phone, email, or random EVP key). examples: - '12345678901' type: string qrPngBase64: description: >- QR code image rendered from the raw payload, base64-encoded PNG (only populated on generation responses). examples: - iVBORw0KGgoAAAANSUhEUgAA... type: string qrPngContentType: description: >- MIME content type of qrPngBase64 (image/png) when an image is present. examples: - image/png type: string raw: description: >- Raw EMV BR Code string; same value as copyPaste, retained for compatibility. examples: - 00020126580014br.gov.bcb.pix... type: string recurrenceUrl: description: >- 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. examples: - pix.example.com/rec/2353c790eefb11eaadc10242ac120002 type: string status: description: Lifecycle status of the payload (e.g. ACTIVE). examples: - ACTIVE type: string txId: description: >- Reference label carried in EMV 62-05, at most 25 characters of a-z, A-Z or 0-9; empty when not present. examples: - Compra042 type: string updatedAt: description: Last-update timestamp in RFC3339 UTC. examples: - '2025-03-07T14:30:00Z' type: string required: - id - kind - merchantName - merchantCity - pixKey - status - createdAt - updatedAt type: object Detail: additionalProperties: false properties: code: description: >- Stable, machine-readable domain error code scoped to the emitting service (format: -NNNN). type: string correlationId: description: Request-scoped correlation identifier echoing X-Request-ID. examples: - req-7a3f9c2e type: string detail: description: >- A human-readable explanation specific to this occurrence of the problem. examples: - Property foo is required but is missing. type: string errors: description: Optional list of individual error details items: $ref: '#/components/schemas/ErrorDetail' type: - array - 'null' instance: description: >- A URI reference that identifies the specific occurrence of the problem. examples: - https://example.com/error-log/abc123 format: uri type: string status: description: HTTP status code examples: - 400 format: int64 type: integer title: description: >- A short, human-readable summary of the problem type. This value should not change between occurrences of the error. examples: - Bad Request type: string type: default: about:blank description: A URI reference to human-readable documentation for the error. examples: - https://example.com/errors/example format: uri type: string upstream: $ref: '#/components/schemas/Upstream' description: >- RFC 9457 extension member: the error a proxied third-party provider reported. Absent unless the emitting service explicitly surfaced one. required: - correlationId type: object ErrorDetail: additionalProperties: false properties: location: description: >- Where the error occurred, e.g. 'body.items[3].tags' or 'path.thing-id' type: string message: description: Error message text type: string value: description: The value at the given location type: object Upstream: additionalProperties: false properties: code: description: The upstream provider's own error code, verbatim. examples: - E4001 type: string message: description: >- The upstream provider's own error message, verbatim (bounded, never its raw response body). examples: - account not found at provider type: string type: object securitySchemes: BearerAuth: bearerFormat: JWT description: JWT bearer token issued by the identity provider. scheme: bearer type: http ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.