> ## 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. # Accept or reject an authorization request > Records the payer's decision. Confirmation and the granting of the authorization and the permission are a single command — there is no second confirmation step. On acceptance the caller may set the payer parameters in the same call; omitted parameters take the normative defaults of Guia v1.2 §6 (notifications enabled, credit line enabled, no maximum amount). On rejection, rejectionReason is mandatory and limited to the two motives the Guia admits. A rejection is NOT answered by the receiving PSP — the flow closes without a response (Guia v1.2 §3.2), so no acknowledgement should be awaited. ## OpenAPI ````yaml /es/openapi/v3-current/pix-lerian-pixauto.yaml post /payer/authorization-requests/{authorization_request_id}/decide 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/{authorization_request_id}/decide: post: tags: - Payer Authorization Requests summary: Accept or reject an authorization request description: >- Records the payer's decision. Confirmation and the granting of the authorization and the permission are a single command — there is no second confirmation step. On acceptance the caller may set the payer parameters in the same call; omitted parameters take the normative defaults of Guia v1.2 §6 (notifications enabled, credit line enabled, no maximum amount). On rejection, rejectionReason is mandatory and limited to the two motives the Guia admits. A rejection is NOT answered by the receiving PSP — the flow closes without a response (Guia v1.2 §3.2), so no acknowledgement should be awaited. operationId: decidePayerAuthorizationRequest parameters: - description: >- Non-zero UUID of the payer account selected by the calling PSP. The PSP must authorize its end user for that account before calling this API. A resource outside the selected account returns 404; a read with no records returns an empty page. See the API overview for the complete trust boundary. example: 0198f3a2-1c4e-7c8b-9d1e-2f3a4b5c6d7e in: header name: X-Account-Id required: true schema: 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 - 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. X-Account-Id is part of the compared request too, so replaying one account's key under another account is divergent rather than a replay. example: payer-decision-20260827-001 in: header name: X-Idempotency required: true schema: maxLength: 64 minLength: 1 type: string - description: >- Payer-side authorization request identifier. On journey 1 this is the counterparty-issued BACEN idSolicRec; on journeys 2–4 it is a local deterministic identifier. Always use the exact value returned by this API when calling this operation, and never forward a QR-journey value as a BACEN idSolicRec. A request or mandate under a different X-Account-Id is answered 404, not 403, so the caller cannot confirm that a resource exists elsewhere. in: path name: authorization_request_id required: true schema: description: >- Payer-side authorization request identifier. On journey 1 this is the counterparty-issued BACEN idSolicRec; on journeys 2–4 it is a local deterministic identifier. Always use the exact value returned by this API when calling this operation, and never forward a QR-journey value as a BACEN idSolicRec. A request or mandate under a different X-Account-Id is answered 404, not 403, so the caller cannot confirm that a resource exists elsewhere. examples: - SC12345678202608276bca619e690 type: string requestBody: content: application/json: examples: accept: summary: Accept and configure the authorization value: decision: ACCEPT parameters: creditLineEnabled: false maximumAmount: amount: '250.00' currency: BRL schedulingNotificationsEnabled: true reject: summary: Reject the authorization request value: decision: REJECT rejectionReason: RejectedByDebtor schema: $ref: '#/components/schemas/AuthorizationDecisionRequest' description: >- The payer's decision, with the parameters to apply when it is an acceptance. required: true responses: '200': content: application/json: examples: accepted: summary: Authorization accepted and mandate created value: authorizationId: 01a044a8-f3bd-7488-a0dc-e8d4be4802be authorizationRequestId: SC12345678202608276bca619e690 status: ACCEPTED rejected: summary: Authorization request rejected without creating a mandate value: authorizationRequestId: SC12345678202608276bca619e690 status: REJECTED schema: $ref: '#/components/schemas/AuthorizationDecisionResponse' 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. '202': content: application/json: examples: accepted: summary: Authorization accepted and mandate created value: authorizationId: 01a044a8-f3bd-7488-a0dc-e8d4be4802be authorizationRequestId: SC12345678202608276bca619e690 status: ACCEPTED rejected: summary: Authorization request rejected without creating a mandate value: authorizationRequestId: SC12345678202608276bca619e690 status: REJECTED schema: $ref: '#/components/schemas/AuthorizationDecisionResponse' description: >- Decision accepted and recorded. ACCEPT creates an authorization and returns authorizationId; REJECT closes the request without one. Communication to the counterparty (pain.012) is asynchronous and is not completed by this response. '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). '404': content: application/json: schema: $ref: '#/components/schemas/Error' description: >- No authorization request with that id is reachable by the caller (PIX-0800). '409': content: application/json: schema: $ref: '#/components/schemas/Error' description: >- The request is no longer pending — already decided, expired, or cancelled by the receiving PSP (PIX-0801). Also PIX-0861 when the request is still pending but its RECURRENCE was cancelled after the request was raised: the decision is refused because no mandate may be granted over a cancelled recurrence, and a changed recurrence travels as a new one (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). X-Account-Id is part of the compared request too, so replaying one account's key under another account is divergent rather than a replay. '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 body parsed, but the decision it describes is not admissible: a rejection without a reason or an acceptance carrying one (PIX-0802, PIX-0803), a maximum amount below the recurrence floor or below its fixed amount (PIX-0806, PIX-0811), or an idSolicRec in the path that is not a well-formed identifier (PIX-0810). '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. 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: AuthorizationDecisionRequest: additionalProperties: false properties: decision: description: The payer's answer to the request. enum: - ACCEPT - REJECT examples: - ACCEPT type: string parameters: $ref: '#/components/schemas/AuthorizationParametersRequest' description: >- The three payer-configurable parameters (Guia v1.2 §6). Accepted only on ACCEPT; an omitted parameter takes its normative default. rejectionReason: description: >- Required on REJECT and forbidden on ACCEPT. NotRecognizedByDebtor: the payer does not recognize the receiver. RejectedByDebtor: the payer has no interest in paying that receiver's charges by Pix Automático. enum: - NotRecognizedByDebtor - RejectedByDebtor examples: - RejectedByDebtor type: string required: - decision type: object AuthorizationDecisionResponse: additionalProperties: false properties: authorizationId: description: >- The mandate that was granted. Absent on a rejection, which grants none. examples: - 01a044a8-f3bd-7488-a0dc-e8d4be4802be type: string authorizationRequestId: description: >- Payer-side request identifier that was decided. It is a BACEN idSolicRec only on journey 1; QR journeys use a local identifier that must not be forwarded to the counterparty. examples: - SC12345678202608276bca619e690 type: string status: description: The status the request reached. enum: - ACCEPTED - REJECTED examples: - ACCEPTED type: string required: - authorizationRequestId - status 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 AuthorizationParametersRequest: additionalProperties: false properties: creditLineEnabled: examples: - false type: boolean maximumAmount: $ref: '#/components/schemas/Money' schedulingNotificationsEnabled: examples: - true type: boolean type: object RawError: additionalProperties: false properties: message: examples: - upstream provider returned 503 type: string status: format: int64 type: integer required: - status - message type: object Money: additionalProperties: false properties: amount: description: >- Decimal string, positive, with at most two fractional digits and at most thirteen integer digits. A string, not a float — binary floating point cannot represent every centavo exactly, and this is a money path. Trailing zeros are not padded: 150.00 and 150 are the same amount. examples: - '149.90' pattern: ^(0\.([1-9][0-9]?|0[1-9])|[1-9][0-9]{0,12}(\.[0-9]{1,2})?)$ type: string currency: description: Pix settles in BRL only. enum: - BRL examples: - BRL type: string required: - amount - currency 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.