> ## 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. # Load a recurrence from a scanned QR Code > Entry point for authorization journeys 2, 3 and 4 (Manual de Padrões §4.4). The app decodes the composed QR Code, detects the journey from its content and reads the recurrence payload over HTTPS directly from the receiving PSP (Manual §2.5.2). Journey 3 carries an immediate first payment which is an ordinary Pix on the existing rail, NOT commanded by this service. Guia v1.2 §3.4 requires its settlement flow to have completed before the authorization flow proceeds, so `immediatePayment.result` must be SETTLED on that journey; anything else aborts the whole journey and creates nothing. A payment that DID settle is never reverted because the authorization then failed — the payer paid what they owed. Journey 4 reads the same field under a different rule. Guia v1.2 §3.5 relaxes the ordering — the payer may have SCHEDULED the charge instead of paying it, and the authorization must still be offered — but forbids the offer after an error: a `result` of FAILED aborts the journey and creates nothing, while SCHEDULED and SETTLED proceed. Omitting the object on journey 4 is admitted and asserts nothing about a payment. Failure to read the payload is absence of data, not rejection of the recurrence: the journey stops with an error and no recurrence state is created. The request this returns is pending — the payer answers it through the decision operation. The response carries lifecycle identifiers and the decision deadline; it does not echo the fetched counterparty or recurrence terms. The channel must obtain the terms it displays to the payer from its provider/messaging integration. ## OpenAPI ````yaml /es/openapi/v3-current/pix-lerian-pixauto.yaml post /payer/authorization-requests/from-qr openapi: 3.1.0 info: contact: name: Lerian Studio url: https://lerian.studio description: >- Pix Automático payer-facing API — deciding an authorization request raised by the receiving end, managing the payer-configurable parameters of a granted mandate, and revoking it (Guia de Implementação do Pix Automático v1.2 §3 and §6). ## Trust boundary This API is **machine-to-machine**. The caller is the client PSP's backend, authenticated with an application token; the token names that application and never one of its customers. The account therefore has to arrive in the request, and it does so in one of two shapes: ten routes take it in the **`X-Account-Id`** header, the same header SPI, DICT and COB use for the same job, and `POST /v1/payer/authorization-requests/from-qr` takes `payerAccountId` in the body — that route creates a pending request for a mandate that does not exist yet, so the account is part of what is being created rather than a scope on an existing resource, and a header beside the body field would be a second source for one value. Either way the value is the caller's **declaration** of which of its own customers it is acting for. **It is not proof that the end user controls that account, and this API cannot make it one.** Authenticating the payer and authorising its own customers against one another is the calling PSP's responsibility. What this end enforces is consistency: an absent header is 400 (PIX-0001) and a malformed account is 400 (PIX-0017 on the header, PIX-0003 in the body), and a resource that exists under a different account than the one named is **404**, not 403: the account is a predicate on the lookup, so this end never learns the resource exists elsewhere and cannot confirm it. Within one lookup, absence and a resource outside the selection get the same answer. license: name: Lerian Studio General License title: Pix Lerian — Pix Automático version: 1.0.0 servers: - url: https://api.example.com/pixauto/v1 description: >- Replace the example host with the URL provided during environment onboarding. security: - BearerAuth: [] tags: - description: >- Authorization requests raised by the receiving end and answered by the payer. A request is answered once. name: Payer Authorization Requests - description: Granted mandates. An authorization is managed for as long as it lives. name: Payer Authorizations - description: >- The payer's forward view of upcoming debits, and the cancellation of one of them. Cancelling a debit leaves the authorization ACTIVE — it stops one charge, not the mandate. The two operations are meant to be used together: the listing is the only place a client receives the scheduled_payment_id the cancellation addresses. name: Payer Scheduled Payments paths: /payer/authorization-requests/from-qr: post: tags: - Payer Authorization Requests summary: Load a recurrence from a scanned QR Code description: >- Entry point for authorization journeys 2, 3 and 4 (Manual de Padrões §4.4). The app decodes the composed QR Code, detects the journey from its content and reads the recurrence payload over HTTPS directly from the receiving PSP (Manual §2.5.2). Journey 3 carries an immediate first payment which is an ordinary Pix on the existing rail, NOT commanded by this service. Guia v1.2 §3.4 requires its settlement flow to have completed before the authorization flow proceeds, so `immediatePayment.result` must be SETTLED on that journey; anything else aborts the whole journey and creates nothing. A payment that DID settle is never reverted because the authorization then failed — the payer paid what they owed. Journey 4 reads the same field under a different rule. Guia v1.2 §3.5 relaxes the ordering — the payer may have SCHEDULED the charge instead of paying it, and the authorization must still be offered — but forbids the offer after an error: a `result` of FAILED aborts the journey and creates nothing, while SCHEDULED and SETTLED proceed. Omitting the object on journey 4 is admitted and asserts nothing about a payment. Failure to read the payload is absence of data, not rejection of the recurrence: the journey stops with an error and no recurrence state is created. The request this returns is pending — the payer answers it through the decision operation. The response carries lifecycle identifiers and the decision deadline; it does not echo the fetched counterparty or recurrence terms. The channel must obtain the terms it displays to the payer from its provider/messaging integration. operationId: createPayerAuthorizationRequestFromQrCode parameters: - description: >- REQUIRED. Client-supplied replay key, at most 64 bytes. A request without it is refused with PIX-0030 @ 400 before the handler runs. Replaying the same key with a divergent method, URL or body is PIX-0031 @ 412. example: payer-decision-20260827-001 in: header name: X-Idempotency required: true schema: maxLength: 64 minLength: 1 type: string requestBody: content: application/json: examples: journey-2: summary: Journey 2 — recurrence only value: payerAccountId: 0198f3a2-1c4e-7c8b-9d1e-2f3a4b5c6d7e qrCodePayload: >- 00020126180014br.gov.bcb.pix5204000053039865802BR5913Fulano de Tal6008BRASILIA62070503***80740014br.gov.bcb.pix2552pix.example.com/rec/2353c790eefb11eaadc10242ac1200026304F2DA journey-3: summary: Journey 3 — immediate Pix already settled value: immediatePayment: endToEndId: E18236120202608271918a1b2c3d4e5f result: SETTLED payerAccountId: 0198f3a2-1c4e-7c8b-9d1e-2f3a4b5c6d7e qrCodePayload: >- 00020101021226740014br.gov.bcb.pix2552pix.example.com/cob/1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d5204000053039865802BR5913Fulano de Tal6008BRASILIA62070503***80740014br.gov.bcb.pix2552pix.example.com/rec/2353c790eefb11eaadc10242ac1200026304A205 journey-4: summary: Journey 4 — due-date charge already scheduled value: immediatePayment: result: SCHEDULED payerAccountId: 0198f3a2-1c4e-7c8b-9d1e-2f3a4b5c6d7e qrCodePayload: >- 00020101021226710014br.gov.bcb.pix2549pix.example.com/cobv/1a2b3c4d5e6f7a8b9c0d1e2f3a4b5204000053039865802BR5913Fulano de Tal6008BRASILIA62070503***80740014br.gov.bcb.pix2552pix.example.com/rec/2353c790eefb11eaadc10242ac12000263048207 schema: $ref: '#/components/schemas/QRCodeAuthorizationRequest' description: >- The scanned QR Code content, with the journey-3 or journey-4 payment outcome when there is one. required: true responses: '200': content: application/json: example: authorizationRequestId: SC12345678202608276bca619e690 expiresAt: '2026-09-26T19:18:38Z' journey: JOURNEY_2 recurrenceId: RR12345678202608276bca619e690 status: RECEIVED schema: $ref: '#/components/schemas/QRCodeAuthorizationResponse' description: >- Recovered duplicate. The same X-Idempotency header was replayed with an identical request, so the FIRST call's response body is returned verbatim and nothing was reprocessed. A replay answers 200 whatever the original status was, so a client tells a replay from a fresh execution by the status code alone. NOTE: this 200 depends on the replay cache. The gate DEGRADES when the cache is unavailable -- it still demands the header, and each route still refuses a second effect through its own durable guard -- but a repeat is then answered by that guard rather than replayed, which for most routes is 409. A client must therefore treat 409 as a possible answer to a retry it believes is a replay, and must not read it as proof that a competing change happened. '201': content: application/json: example: authorizationRequestId: SC12345678202608276bca619e690 expiresAt: '2026-09-26T19:18:38Z' journey: JOURNEY_2 recurrenceId: RR12345678202608276bca619e690 status: RECEIVED schema: $ref: '#/components/schemas/QRCodeAuthorizationResponse' description: Recurrence loaded and presented as a pending authorization request. '400': content: application/json: schema: $ref: '#/components/schemas/Error' description: >- Malformed request, missing required input, invalid field value or invalid idempotency key (PIX-0001, PIX-0002, PIX-0003, PIX-0015, PIX-0017, PIX-0030, plus operation-specific PIX codes). X-Idempotency absent or longer than 64 bytes (PIX-0030). '401': content: application/json: example: code: PIX-0004 message: Invalid or expired authentication credentials. title: Unauthorized schema: $ref: '#/components/schemas/Error' description: The caller is not authenticated (PIX-0004). '403': content: application/json: example: code: PIX-0005 message: You do not have permission to perform this operation. title: Forbidden schema: $ref: '#/components/schemas/Error' description: >- The caller is authenticated but not entitled to this resource (PIX-0005). '409': content: application/json: schema: $ref: '#/components/schemas/Error' description: >- The recurrence already has an active pending request, or is already authorized (PIX-0809). '412': content: application/json: schema: $ref: '#/components/schemas/Error' description: >- X-Idempotency replayed with a divergent request — a different method, URL (including the path parameter) or body (PIX-0031). '415': content: application/json: example: code: PIX-0016 message: >- The request body must be sent with Content-Type: application/json. title: Unsupported Media Type schema: $ref: '#/components/schemas/Error' description: >- The request body carries a media type this operation does not admit (PIX-0016). '422': content: application/json: schema: $ref: '#/components/schemas/Error' description: >- The recurrence payload location encoded in the QR Code is malformed, non-HTTPS, too long, points to a non-public target, or uses a host outside the configured allowlist (PIX-0808). No access is attempted. '500': content: application/json: example: code: PIX-0000 message: >- The server encountered an unexpected error. Please try again later. title: Internal Server Error schema: $ref: '#/components/schemas/Error' description: >- Unexpected internal failure (PIX-0000). Details never travel in the envelope. '502': content: application/json: schema: $ref: '#/components/schemas/Error' description: >- The recurrence payload could not be read from the receiving PSP (PIX-0807). default: content: application/json: schema: $ref: '#/components/schemas/Error' description: >- Any other error returned by the handler uses the same PIX error envelope. The HTTP status and code identify the concrete failure. components: schemas: QRCodeAuthorizationRequest: additionalProperties: false properties: immediatePayment: $ref: '#/components/schemas/ImmediatePaymentRequest' description: >- How the payment-or-scheduling flow of the charge ended. REQUIRED on journey 3, where Guia v1.2 §3.4 forbids proceeding with the authorization before the settlement flow completed. On journey 4 it is optional, and a FAILED result is refused: §3.5 forbids the offer that would follow an error. Ignored on journey 2, which carries no charge. payerAccountId: description: >- The payer account the authorization would apply to, selected by the calling PSP among its own customers. A value that is not a non-zero UUID is refused with 400. This is the one route of the payer surface that carries the account in the BODY rather than the X-Account-Id header: a QR journey creates a mandate that does not exist yet, so the account is part of what is being created. examples: - 0198f3a2-1c4e-7c8b-9d1e-2f3a4b5c6d7e format: uuid not: const: 00000000-0000-0000-0000-000000000000 pattern: >- ^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$ type: string qrCodePayload: description: >- Raw EMV content read from the QR Code. The app decodes it, detects the journey and reads the recurrence payload from the location it carries. examples: - >- 00020126180014br.gov.bcb.pix5204000053039865802BR5913Fulano de Tal6008BRASILIA62070503***80740014br.gov.bcb.pix2552pix.example.com/rec/2353c790eefb11eaadc10242ac1200026304F2DA maxLength: 4096 type: string required: - qrCodePayload - payerAccountId type: object QRCodeAuthorizationResponse: additionalProperties: false properties: authorizationRequestId: description: >- Local payer-side request identifier created for the QR journey. Use this exact value on the decision route; do not forward it as a BACEN idSolicRec. examples: - SC12345678202608276bca619e690 type: string expiresAt: examples: - '2026-09-26T19:18:38Z' format: date-time type: string journey: description: The journey detected from the QR Code content. enum: - JOURNEY_2 - JOURNEY_3 - JOURNEY_4 examples: - JOURNEY_2 type: string recurrenceId: examples: - RR12345678202608276bca619e690 type: string status: description: The pending status the request was born in. enum: - RECEIVED examples: - RECEIVED type: string required: - authorizationRequestId - recurrenceId - status - journey - expiresAt type: object Error: additionalProperties: false properties: code: examples: - PIX-0142 type: string fields: additionalProperties: type: string type: object headers: additionalProperties: type: string type: object message: examples: - claim_id is required type: string paths: additionalProperties: type: string type: object query_params: additionalProperties: type: string type: object raw: $ref: '#/components/schemas/RawError' title: examples: - Invalid Claim Request type: string required: - code - title - message type: object ImmediatePaymentRequest: additionalProperties: false properties: endToEndId: description: >- End-to-end identifier of the Pix, in the BACEN format: E, an 8-digit ISPB, a 12-digit UTC timestamp and an 11-character sequential. REQUIRED once result is SETTLED, so the mandate can be tied to the Pix that paid for it; a settlement this service cannot name is refused. Optional on SCHEDULED, where the payment has not been submitted and its identifier does not exist yet, and validated whenever it is supplied. examples: - E18236120202608271918a1b2c3d4e5f type: string result: description: >- How the payment-or-scheduling flow of the charge ended. SETTLED is the only result journey 3 admits. Journey 4 admits SETTLED and SCHEDULED, and refuses FAILED. enum: - SETTLED - SCHEDULED - FAILED examples: - SETTLED type: string required: - result type: object RawError: additionalProperties: false properties: message: examples: - upstream provider returned 503 type: string status: format: int64 type: integer required: - status - message 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.