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.

POST /payer/authorization-requests/from-qr

cURL

journey-2

curl --request POST \ --url https://api.example.com/pixauto/v1/payer/authorization-requests/from-qr \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --header 'X-Idempotency: <x-idempotency>' \ --data ' { "payerAccountId": "0198f3a2-1c4e-7c8b-9d1e-2f3a4b5c6d7e", "qrCodePayload": "00020126180014br.gov.bcb.pix5204000053039865802BR5913Fulano de Tal6008BRASILIA62070503***80740014br.gov.bcb.pix2552pix.example.com/rec/2353c790eefb11eaadc10242ac1200026304F2DA" } '

200

{
  "authorizationRequestId": "SC12345678202608276bca619e690",
  "expiresAt": "2026-09-26T19:18:38Z",
  "journey": "JOURNEY_2",
  "recurrenceId": "RR12345678202608276bca619e690",
  "status": "RECEIVED"
}

Authorizations

Authorization · string · header · required

JWT bearer token issued by the identity provider.

Headers

X-Idempotency · string · required

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.

Required string length: 1 - 64

Body

application/json

The scanned QR Code content, with the journey-3 or journey-4 payment outcome when there is one.

payerAccountId · string<uuid> · required

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.

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}$

Example:

"0198f3a2-1c4e-7c8b-9d1e-2f3a4b5c6d7e"

qrCodePayload · string · required

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.

Maximum string length: 4096

Example:

"00020126180014br.gov.bcb.pix5204000053039865802BR5913Fulano de Tal6008BRASILIA62070503***80740014br.gov.bcb.pix2552pix.example.com/rec/2353c790eefb11eaadc10242ac1200026304F2DA"

immediatePayment · object

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.

Show child attributes

Response

200

application/json

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.

authorizationRequestId · string · required

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.

Example:

"SC12345678202608276bca619e690"

expiresAt · string<date-time> · required

Example:

"2026-09-26T19:18:38Z"

journey · enum<string> · required

The journey detected from the QR Code content.

Available options: JOURNEY_2, JOURNEY_3, JOURNEY_4

Example:

"JOURNEY_2"

recurrenceId · string · required

Example:

"RR12345678202608276bca619e690"

status · enum<string> · required

The pending status the request was born in.

Available options: RECEIVED

Example:

"RECEIVED"