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"
}
'

201

{
  "authorizationRequestId": "SC12345678202608276bca619e690",
  "expiresAt": "2026-09-26T19:18:38Z",
  "journey": "JOURNEY_2",
  "recurrenceId": "RR12345678202608276bca619e690",
  "status": "RECEIVED",
  "recurrence": {
    "amount": {
      "amount": "89.90",
      "currency": "BRL"
    },
    "contractDescription": "Mensalidade do plano de academia",
    "endDate": "2027-08-10",
    "periodicity": "MONTHLY",
    "receiver": {
      "name": "Academia Corpo em Movimento Ltda",
      "taxId": {
        "type": "CNPJ",
        "value": "11222333000181"
      }
    },
    "retryPolicy": "ACCEPT_3R_7D",
    "snapshotVersion": 1,
    "startDate": "2026-09-10"
  }
}

Autorizações

Authorization · string · header · obrigatório

JWT bearer token issued by the identity provider.

Cabeçalhos

X-Idempotency · string · obrigatório

REQUIRED. Client-supplied replay key, at most 64 bytes. A request without it is refused with PIX-0030 @ 400 before the handler runs. An identical resend within 1 hour returns the original response, status included, with X-Idempotency-Replayed: true. Reusing the key with a divergent method, URL or body is PIX-0031 @ 412.

Required string length: 1 - 64

Corpo

application/json

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

payerAccountId · string<uuid> · obrigatório

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

Exemplo:

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

qrCodePayload · string · obrigatório

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

Exemplo:

"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

Resposta

201

application/json

Recurrence loaded and presented as a pending authorization request.

authorizationRequestId · string · obrigatório

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.

Exemplo:

"SC12345678202608276bca619e690"

expiresAt · string<date-time> · obrigatório

Exemplo:

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

journey · enum<string> · obrigatório

The journey detected from the QR Code content.

Opções disponíveis: JOURNEY_2, JOURNEY_3, JOURNEY_4

Exemplo:

"JOURNEY_2"

recurrenceId · string · obrigatório

Exemplo:

"RR12345678202608276bca619e690"

status · enum<string> · obrigatório

The pending status the request was born in.

Opções disponíveis: RECEIVED

Exemplo:

"RECEIVED"

recurrence · object · obrigatório

Terms of the recurrence the payer is asked to authorize: the receiver, periodicity, dates, amount shape and retry policy. They are the terms this institution holds after recording the request: when the payload read from the QR Code carries a version no newer than the one already held, the held terms are returned. They are a snapshot as of recording: newer terms can arrive later, and a replay answers this response verbatim, so GET the request for the current terms before deciding.

Show child attributes