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

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

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

{
  "code": "PIX-0142",
  "message": "claim_id is required",
  "title": "Invalid Claim Request",
  "fields": {},
  "headers": {},
  "paths": {},
  "query_params": {},
  "raw": {
    "message": "upstream provider returned 503",
    "status": 123
  }
}

{
  "code": "PIX-0004",
  "message": "Invalid or expired authentication credentials.",
  "title": "Unauthorized"
}

{
  "code": "PIX-0005",
  "message": "You do not have permission to perform this operation.",
  "title": "Forbidden"
}

{
  "code": "PIX-0142",
  "message": "claim_id is required",
  "title": "Invalid Claim Request",
  "fields": {},
  "headers": {},
  "paths": {},
  "query_params": {},
  "raw": {
    "message": "upstream provider returned 503",
    "status": 123
  }
}

{
  "code": "PIX-0142",
  "message": "claim_id is required",
  "title": "Invalid Claim Request",
  "fields": {},
  "headers": {},
  "paths": {},
  "query_params": {},
  "raw": {
    "message": "upstream provider returned 503",
    "status": 123
  }
}

{
  "code": "PIX-0016",
  "message": "The request body must be sent with Content-Type: application/json.",
  "title": "Unsupported Media Type"
}

{
  "code": "PIX-0142",
  "message": "claim_id is required",
  "title": "Invalid Claim Request",
  "fields": {},
  "headers": {},
  "paths": {},
  "query_params": {},
  "raw": {
    "message": "upstream provider returned 503",
    "status": 123
  }
}

{
  "code": "PIX-0000",
  "message": "The server encountered an unexpected error. Please try again later.",
  "title": "Internal Server Error"
}

{
  "code": "PIX-0142",
  "message": "claim_id is required",
  "title": "Invalid Claim Request",
  "fields": {},
  "headers": {},
  "paths": {},
  "query_params": {},
  "raw": {
    "message": "upstream provider returned 503",
    "status": 123
  }
}

{
  "code": "PIX-0142",
  "message": "claim_id is required",
  "title": "Invalid Claim Request",
  "fields": {},
  "headers": {},
  "paths": {},
  "query_params": {},
  "raw": {
    "message": "upstream provider returned 503",
    "status": 123
  }
}

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.

POST

payer

authorization-requests

from-qr

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

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

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

{
  "code": "PIX-0142",
  "message": "claim_id is required",
  "title": "Invalid Claim Request",
  "fields": {},
  "headers": {},
  "paths": {},
  "query_params": {},
  "raw": {
    "message": "upstream provider returned 503",
    "status": 123
  }
}

{
  "code": "PIX-0004",
  "message": "Invalid or expired authentication credentials.",
  "title": "Unauthorized"
}

{
  "code": "PIX-0005",
  "message": "You do not have permission to perform this operation.",
  "title": "Forbidden"
}

{
  "code": "PIX-0142",
  "message": "claim_id is required",
  "title": "Invalid Claim Request",
  "fields": {},
  "headers": {},
  "paths": {},
  "query_params": {},
  "raw": {
    "message": "upstream provider returned 503",
    "status": 123
  }
}

{
  "code": "PIX-0142",
  "message": "claim_id is required",
  "title": "Invalid Claim Request",
  "fields": {},
  "headers": {},
  "paths": {},
  "query_params": {},
  "raw": {
    "message": "upstream provider returned 503",
    "status": 123
  }
}

{
  "code": "PIX-0016",
  "message": "The request body must be sent with Content-Type: application/json.",
  "title": "Unsupported Media Type"
}

{
  "code": "PIX-0142",
  "message": "claim_id is required",
  "title": "Invalid Claim Request",
  "fields": {},
  "headers": {},
  "paths": {},
  "query_params": {},
  "raw": {
    "message": "upstream provider returned 503",
    "status": 123
  }
}

{
  "code": "PIX-0000",
  "message": "The server encountered an unexpected error. Please try again later.",
  "title": "Internal Server Error"
}

{
  "code": "PIX-0142",
  "message": "claim_id is required",
  "title": "Invalid Claim Request",
  "fields": {},
  "headers": {},
  "paths": {},
  "query_params": {},
  "raw": {
    "message": "upstream provider returned 503",
    "status": 123
  }
}

{
  "code": "PIX-0142",
  "message": "claim_id is required",
  "title": "Invalid Claim Request",
  "fields": {},
  "headers": {},
  "paths": {},
  "query_params": {},
  "raw": {
    "message": "upstream provider returned 503",
    "status": 123
  }
}

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

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.

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"

DICT and Pix keys

Collections and BR Codes

Payments and refunds

Pix Automático API

Error handling

Load a recurrence from a scanned QR Code

Authorizations

Headers

Body

Response