> ## 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. On journey 3, also send `immediatePayment.settlementConfirmedAt`, the instant your institution received the pacs.002 that confirmed that settlement. The BACEN requires it in the pain.012 that confirms a journey 3 authorization. It is optional here: a request without it is still created, but once the payer accepts, the authorization is NOT communicated to the BACEN until that instant is known, and no operation supplies it afterwards. An instant more than 2 minutes ahead of the server clock is refused with 400 (up to 2 minutes ahead is accepted as clock skew), and the field is refused on journey 4. 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. The payer account is resolved in this institution's account directory (CRM) before the payload is read: the document, branch and account number it is held under are what every later message to the BACEN about the mandate carries. An account the directory does not hold is refused with 422 (PIX-0813). An account the directory holds but whose stored data cannot be used — data the directory itself rejects, a missing holder, or data that do not form a valid payer identity — is refused with 422 (PIX-0818), and so is a call from a tenant with no directory credentials provisioned (PIX-0819): neither changes on a retry. A directory that cannot resolve it for any other reason answers 503 (PIX-0814): it cannot be reached, it refused this service's credentials, or it is not configured in this deployment. None of these reads the payload or creates anything. 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. A payload that lacks the receiving participant's ISPB, the contract, the debtor or its creation entry, or whose receiver name, contract or debtor name exceeds what the mandate block admits (140, 35 and 140 bytes), is unreadable in the same sense (PIX-0807). 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 /en/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: most routes take it in the **`X-Account-Id`** header, the same header SPI, DICT and COB use for the same job, and the route that CREATES the resource the account belongs to takes `payerAccountId` in the body — `POST /v1/payer/authorization-requests/from-qr`, which opens a pending request for a mandate that does not exist yet. On that route, 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.1.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. On journey 3, also send `immediatePayment.settlementConfirmedAt`, the instant your institution received the pacs.002 that confirmed that settlement. The BACEN requires it in the pain.012 that confirms a journey 3 authorization. It is optional here: a request without it is still created, but once the payer accepts, the authorization is NOT communicated to the BACEN until that instant is known, and no operation supplies it afterwards. An instant more than 2 minutes ahead of the server clock is refused with 400 (up to 2 minutes ahead is accepted as clock skew), and the field is refused on journey 4. 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. The payer account is resolved in this institution's account directory (CRM) before the payload is read: the document, branch and account number it is held under are what every later message to the BACEN about the mandate carries. An account the directory does not hold is refused with 422 (PIX-0813). An account the directory holds but whose stored data cannot be used — data the directory itself rejects, a missing holder, or data that do not form a valid payer identity — is refused with 422 (PIX-0818), and so is a call from a tenant with no directory credentials provisioned (PIX-0819): neither changes on a retry. A directory that cannot resolve it for any other reason answers 503 (PIX-0814): it cannot be reached, it refused this service's credentials, or it is not configured in this deployment. None of these reads the payload or creates anything. 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. A payload that lacks the receiving participant's ISPB, the contract, the debtor or its creation entry, or whose receiver name, contract or debtor name exceeds what the mandate block admits (140, 35 and 140 bytes), is unreadable in the same sense (PIX-0807). 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 settlementConfirmedAt: '2026-08-27T19:18:21Z' 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 is 409. A client must therefore treat 200 and 409 as possible answers to a retry it believes is a replay, and must not read either 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: >- The body is not valid JSON (PIX-0010), is missing a required field or carries an invalid one (PIX-0002, PIX-0003, naming each field); and the QR Code and charge-flow refusals, all PIX-0003 naming the field: fields.qrCodePayload when the code is not a decodable BR Code, carries no recurrence location, or carries two locations naming different receiving PSPs; fields.payerAccountId when the account is not a non-zero UUID; fields.immediatePayment when journey 3 arrives without a SETTLED charge payment; fields.immediatePayment.result when journey 4 reports FAILED or an unknown result; fields.immediatePayment.endToEndId when a settled payment carries none or a malformed one; fields.immediatePayment.settlementConfirmedAt when a journey 3 instant lies more than 2 minutes in the future or journey 4 carries one. None of them creates anything. X-Idempotency absent or longer than 64 bytes (PIX-0030). '401': content: application/json: example: code: PIX-0010 message: The request could not be processed due to a client-side error. title: Client Error schema: $ref: '#/components/schemas/Error' description: >- The credentials were refused before the handler ran: absent, invalid or expired. Branch on the 401 status, not the body code, which depends on the refusing layer: the authorization middleware answers the generic client-error code PIX-0010; in multi-tenant deployments the tenant layer may answer a missing, malformed or tenantless token with its own {code,title,message} body, under codes such as MISSING_TOKEN, INVALID_TENANT or UNAUTHORIZED. '403': content: application/json: example: code: PIX-0010 message: The request could not be processed due to a client-side error. title: Client Error schema: $ref: '#/components/schemas/Error' description: >- The caller was refused before the handler ran. Branch on the 403 status, not the body code, which depends on the refusing layer: the authorization middleware answers the generic client-error code PIX-0010 when the caller is not entitled to this resource and action; in multi-tenant deployments the tenant layer may answer with its own {code,title,message} body, such as code 0131 (Service Suspended or Access Denied) when the tenant's access to this service is suspended, purged or denied. '409': content: application/json: schema: $ref: '#/components/schemas/Error' description: >- The recurrence already has an active pending request, or is already authorized (PIX-0809). PIX-0861 when the recurrence is already cancelled (payer revocation or the receiving PSP's cancellation): a cancelled recurrence is not re-solicitable, and a changed one travels as a new idRec (Guia v1.2 §3.8.1). '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. Or the payer account is not held, or not held unambiguously, in the account directory (PIX-0813); or the directory holds it but its stored data cannot be used until corrected (PIX-0818); or the calling tenant has no directory credentials provisioned (PIX-0819). None of these changes on a retry. '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, or what it returned is not admissible recurrence terms — including an idRec that is not well formed, or a payload that lacks the receiving participant's ISPB, the contract, the debtor or the creation entry the mandate requires, or carries a receiver name, contract or debtor name longer than the mandate block admits (140, 35 and 140 bytes) (PIX-0807). Nothing was created; the read may be retried. '503': content: application/json: schema: $ref: '#/components/schemas/Error' description: >- The account directory (CRM) could not resolve the payer account (PIX-0814): it could not be reached, it refused this service's credentials, or it is not configured in this deployment. Nothing was created; retry later with the same X-Idempotency. 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. In multi-tenant deployments the tenant layer can also refuse before the handler runs -- for example 404 TENANT_NOT_FOUND or 503 SERVICE_UNAVAILABLE -- with its own {code,title,message} body; branch on the HTTP status. 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 settlementConfirmedAt: description: >- Instant, in RFC 3339, at which the payer's institution received the pacs.002 that confirmed the settlement of the journey 3 immediate payment. The BACEN requires it in the pain.012 that confirms a journey 3 authorization. Optional: without it the request is still created, but once the payer accepts, the authorization is not communicated to the BACEN until this instant is known, so send it whenever you have it. An instant more than 2 minutes ahead of the server clock is refused with 400; up to 2 minutes ahead is accepted as clock skew and stored as sent. Refused on journey 4, which carries no immediate payment; ignored on journey 2 together with the rest of this object. examples: - '2026-08-27T19:18:21Z' format: date-time 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.