components: schemas: AuthorizationCancellationBody: additionalProperties: false properties: reason: description: "Free-text note for the PAYER's own audit trail. It is NOT the value sent to the counterparty: the receiving PSP is told a fixed code this end chooses, which the response echoes as counterpartyReason." examples: - Payer requested revocation in the mobile app maxLength: 200 type: string type: object AuthorizationCancellationResponse: additionalProperties: false properties: authorizationId: examples: - 01a044a8-f3bd-7488-a0dc-e8d4be4802be type: string cancelledScheduledPayments: examples: - 0 format: int64 type: integer counterpartyReason: examples: - SLDB type: string preservedScheduledPayments: examples: - 0 format: int64 type: integer status: examples: - CANCELLED type: string required: - authorizationId - status - counterpartyReason - cancelledScheduledPayments - preservedScheduledPayments type: object 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 AuthorizationHistoryItem: additionalProperties: false properties: actor: description: Who caused the transition. enum: - PAYER - PAYER_PSP - RECEIVER - RECEIVER_PSP - SYSTEM examples: - PAYER type: string correlationId: description: Correlation of the request that caused it, when there was one. examples: - 0198f3a2-1c4e-7c8b-9d1e-2f3a4b5c6d70 type: string id: description: Identifier of the audit entry. examples: - 01a044a8-f72e-7877-af77-6b1496e92680 type: string newStatus: description: State the mandate entered. examples: - CANCELLED type: string occurredAt: description: When the transition happened. This is the ordering key of the surface, not the write instant. examples: - "2026-08-27T19:18:39Z" format: date-time type: string operationId: description: Identifier of the external invocation that caused it, when applicable. examples: - 01a044a8-f3bd-7488-a0dc-e8d4be4802bf type: string previousStatus: description: State the mandate left. Absent on the entry that opened its life. examples: - APPROVED type: string required: - id - occurredAt - newStatus - actor type: object AuthorizationHistoryPage: additionalProperties: false properties: items: description: Empty array when there are no results — never null. items: $ref: "#/components/schemas/AuthorizationHistoryItem" type: array next_cursor: description: Opaque cursor for the next page. NULL on the last page, never an empty string. examples: - eyJ0IjoiMjAyNi0wOC0yN1QxODo0MjowMFoiLCJpIjoiMDE5OGYzYTEtN2M0Mi03ZGUxLWEwMjQtYjFmMGI3ZTljMzAxIn0= type: - string - "null" prev_cursor: description: Opaque cursor for the previous page. These listings do not issue a backwards cursor, so the value is null. type: - string - "null" required: - items - next_cursor - prev_cursor type: object AuthorizationItem: additionalProperties: false properties: authorizedAt: description: When the mandate was granted. examples: - "2026-08-27T19:18:38Z" format: date-time type: string createdAt: examples: - "2026-08-27T19:18:38Z" format: date-time type: string id: description: Internal identifier of the mandate. examples: - 01a044a8-f3bd-7488-a0dc-e8d4be4802be type: string journey: description: Journey that granted the mandate. enum: - JOURNEY_1 - JOURNEY_2 - JOURNEY_3 - JOURNEY_4 examples: - JOURNEY_1 type: string parameters: $ref: "#/components/schemas/AuthorizationParametersBody" recurrenceId: description: BACEN idRec of the recurrence it covers. examples: - RR12345678202608276bca619e690 type: string status: description: Lifecycle status of the mandate. AWAITING_CONCLUSION means the payer granted it and the receiving PSP has not yet concluded the process — it is NOT active at BACEN (Manual de Tempos do Pix v7.0 §3.2). enum: - AWAITING_CONCLUSION - APPROVED - REJECTED - EXPIRED - CANCELLED examples: - APPROVED type: string terminatedAt: description: "When the mandate ENDED — the instant it became REJECTED, EXPIRED or CANCELLED. Absent while it has not ended, which covers an APPROVED mandate and an AWAITING_CONCLUSION one alike: absence means the mandate has not ended, never that it is active." examples: - "2026-08-27T20:00:00Z" format: date-time type: string updatedAt: examples: - "2026-08-27T20:00:00Z" format: date-time type: string required: - id - recurrenceId - status - journey - parameters - authorizedAt - createdAt - updatedAt type: object AuthorizationPage: additionalProperties: false properties: items: description: Empty array when there are no results — never null. items: $ref: "#/components/schemas/AuthorizationItem" type: array next_cursor: description: Opaque cursor for the next page. NULL on the last page, never an empty string. examples: - eyJ0IjoiMjAyNi0wOC0yN1QxODo0MjowMFoiLCJpIjoiMDE5OGYzYTEtN2M0Mi03ZGUxLWEwMjQtYjFmMGI3ZTljMzAxIn0= type: - string - "null" prev_cursor: description: Opaque cursor for the previous page. These listings do not issue a backwards cursor, so the value is null. type: - string - "null" required: - items - next_cursor - prev_cursor type: object AuthorizationParametersBody: additionalProperties: false properties: creditLineEnabled: examples: - false type: boolean maximumAmount: $ref: "#/components/schemas/Money" schedulingNotificationsEnabled: examples: - false type: boolean required: - schedulingNotificationsEnabled - creditLineEnabled type: object AuthorizationParametersPatch: additionalProperties: false properties: creditLineEnabled: description: Whether a pre-approved credit line may be drawn on when the balance is short at settlement (Guia v1.2 §6.3). Null restores the normative default, which is true. examples: - false type: - boolean - "null" maximumAmount: description: Ceiling per payment under this authorization. Null removes the ceiling, which is its normative default (Guia v1.2 §6). Checked at scheduling, never at settlement, and never shared with the receiving user or their PSP (§6.1). examples: - amount: "250.75" currency: BRL oneOf: - $ref: "#/components/schemas/Money" - type: "null" schedulingNotificationsEnabled: description: Governs ONLY the notice of a successful scheduling (Guia v1.2 §6.2). Null restores the normative default, which is true — a reset is NOT an opt-out. examples: - false type: - boolean - "null" type: object AuthorizationParametersRequest: additionalProperties: false properties: creditLineEnabled: examples: - false type: boolean maximumAmount: $ref: "#/components/schemas/Money" schedulingNotificationsEnabled: examples: - true type: boolean type: object AuthorizationParametersResponse: additionalProperties: false properties: authorizedAt: examples: - "2026-08-27T19:18:38Z" format: date-time type: string createdAt: examples: - "2026-08-27T19:18:38Z" format: date-time type: string id: examples: - 01a044a8-f3bd-7488-a0dc-e8d4be4802be type: string journey: examples: - JOURNEY_1 type: string parameters: $ref: "#/components/schemas/AuthorizationParametersBody" recurrenceId: examples: - RR12345678202608276bca619e690 type: string status: examples: - APPROVED type: string updatedAt: examples: - "2026-08-27T19:20:00Z" format: date-time type: string required: - id - recurrenceId - status - journey - parameters - authorizedAt - createdAt - updatedAt type: object AuthorizationRequestItem: additionalProperties: false properties: authorizationRequestId: description: Payer-side request identifier. It is the counterparty idSolicRec on journey 1 and a local identifier on QR journeys; always pass this exact value to the decision route. examples: - SC12345678202608276bca619e690 type: string decidedAt: description: When the payer decided. Absent while the request is still pending. examples: - "2026-08-27T19:20:00Z" format: date-time type: string expiresAt: description: Decision deadline. At most 30 days from creation (Guia v1.2 §3.2). examples: - "2026-09-26T19:18:38Z" format: date-time type: string journey: description: "Authorization journey that produced the request: JOURNEY_1 for a request the receiving PSP sent through the messaging callback (pain.009), JOURNEY_2 to JOURNEY_4 for one created from a scanned QR Code." examples: - JOURNEY_2 type: string receivedAt: description: When this end received the request. examples: - "2026-08-27T19:18:38Z" format: date-time type: string recurrenceId: description: BACEN idRec of the recurrence the request covers. examples: - RR12345678202608276bca619e690 type: string rejectionReason: description: Motive the payer gave when refusing the recurrence. Present only when status is REJECTED. enum: - NotRecognizedByDebtor - RejectedByDebtor examples: - NotRecognizedByDebtor type: string status: description: "Status the request currently holds -- pending on the listing surface, any lifecycle status on the individual GET. A pending request reads RECEIVED: it is the status this end records when a request reaches it, and the only pending status it writes." examples: - RECEIVED type: string required: - authorizationRequestId - recurrenceId - status - expiresAt - receivedAt type: object AuthorizationRequestPage: additionalProperties: false properties: items: description: Empty array when there are no results — never null. items: $ref: "#/components/schemas/AuthorizationRequestItem" type: array next_cursor: description: Opaque cursor for the next page. NULL on the last page, never an empty string. examples: - eyJ0IjoiMjAyNi0wOC0yN1QxODo0MjowMFoiLCJpIjoiMDE5OGYzYTEtN2M0Mi03ZGUxLWEwMjQtYjFmMGI3ZTljMzAxIn0= type: - string - "null" prev_cursor: description: Opaque cursor for the previous page. These listings do not issue a backwards cursor, so the value is null. type: - string - "null" required: - items - next_cursor - prev_cursor 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 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.95" 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 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 RawError: additionalProperties: false properties: message: examples: - upstream provider returned 503 type: string status: format: int64 type: integer required: - status - message type: object ScheduledPaymentCancellationResponse: additionalProperties: false properties: amount: description: Amount in BRL that will not be debited, as a decimal string with two places. Money never travels as a number. examples: - "150.00" type: string cancelledAt: description: Instant the cancellation took effect on this end, in UTC. It is this end's own clock reading, not a value from the request. examples: - "2026-09-09T15:00:00Z" format: date-time type: string counterpartyReason: description: camt.055 motivoDoCancelamento sent to the receiving PSP. Always SLBD on this route — the paying user ended ONE debit. It is never CCLD, which would state that the authorization itself fell. examples: - SLBD type: string endToEndId: description: BACEN end-to-end identifier of the charge. It is the key the receiving PSP reconciles the camt.055 against; the internal identifier above names nothing the other institution can match. examples: - E1234567820260810120011a2b3c4d5e type: string scheduledDate: description: "Business date the debit would have settled on, as a YYYY-MM-DD calendar date. It is a date and not an instant: there is no time of day and no time zone to interpret." examples: - "2026-09-10" format: date type: string scheduledPaymentId: description: Internal identifier of the scheduled debit that was cancelled. examples: - 0198f3a2-1c4e-7c8b-9d1e-2f3a4b5c6d40 format: uuid type: string status: description: Lifecycle status the debit now holds. Always CANCELLED on a 202; it is returned rather than assumed so the caller reads a fact. examples: - CANCELLED type: string required: - scheduledPaymentId - endToEndId - status - counterpartyReason - scheduledDate - amount - cancelledAt type: object ScheduledPaymentItem: additionalProperties: false properties: amount: $ref: "#/components/schemas/Money" description: Amount that will be debited. authorizationId: description: "Mandate the debit was scheduled under. ABSENT rather than null when the debit carries none, as on a same-day resend (purpose RIFL) answering a failed attempt." format: uuid type: string createdAt: format: date-time type: string id: description: Internal identifier of the scheduled debit. Pass it as {scheduled_payment_id} to POST /v1/payer/scheduled-payments/{scheduled_payment_id}/cancel — this listing is the only published operation that returns it. format: uuid type: string maximumAmountSnapshot: $ref: "#/components/schemas/Money" description: The maximum amount in force AT SCHEDULING TIME, written once and never updated — a later change to the mandate does not reach this debit (Guia v1.2 §6.1). Absent when no ceiling was in force. purpose: description: "Why the debit exists: AGND a scheduled collection, NTAG a post-due retry, RIFL a same-day resend after a failed attempt." enum: - AGND - NTAG - RIFL type: string recurrenceId: description: BACEN idRec of the recurrence the debit belongs to. ABSENT rather than empty on a debit that belongs to no recurrence. type: string scheduledDate: description: Business date the debit settles on, after business-day and local-holiday adjustment. A calendar date (YYYY-MM-DD) with no time of day and no zone. format: date type: string status: description: "Lifecycle state of the debit. Only a SCHEDULED debit can be cancelled; the cancellation route answers 409 for any other state. Only SCHEDULED and CANCELLED are produced: a debit that settled keeps reading SCHEDULED, and settlement.outcome carries the payment result." enum: - SCHEDULED - DISPATCHING - SETTLED - FAILED - CANCELLED - RECONCILING type: string updatedAt: format: date-time type: string settlement: $ref: "#/components/schemas/ScheduledPaymentSettlement" description: "Payment outcome of the debit, read from its LATEST settlement attempt. ABSENT rather than null while no attempt exists. It is the field that says whether the debit was paid: status keeps the scheduling lifecycle and a debit that settled keeps reading SCHEDULED. This listing reads a replica, so an attempt that has just concluded can still read PROCESSING for a moment. The settlement_* events push only negative or pending outcomes; a COMPLETED settlement emits no event and is seen only by re-reading this listing (or the account's outgoing Pix)." required: - id - amount - scheduledDate - purpose - status - createdAt - updatedAt type: object ScheduledPaymentPage: additionalProperties: false properties: items: description: Empty array when there are no results — never null. An empty array means the account named in X-Account-Id has no scheduled debit. items: $ref: "#/components/schemas/ScheduledPaymentItem" type: array next_cursor: description: Opaque cursor for the next page. NULL on the last page, never an empty string. examples: - eyJ0IjoiMjAyNi0wOC0yN1QxODo0MjowMFoiLCJpIjoiMDE5OGYzYTEtN2M0Mi03ZGUxLWEwMjQtYjFmMGI3ZTljMzAxIn0= type: - string - "null" prev_cursor: description: Opaque cursor for the previous page. These listings do not issue a backwards cursor, so the value is null. type: - string - "null" required: - items - next_cursor - prev_cursor type: object ScheduledPaymentSettlement: additionalProperties: false properties: concludedAt: description: When the attempt reached COMPLETED or REJECTED. RFC 3339, UTC. Present if and only if outcome is COMPLETED or REJECTED. examples: - "2026-09-10T12:00:04Z" format: date-time type: string endToEndId: description: "End-to-end identifier minted for this attempt's settlement order. It does not prove the order reached the rail: an order still being prepared (published as PROCESSING) or one REJECTED with a failureCategory other than REJECTED_BY_RAIL never did." examples: - E12345678202609101200a1b2c3d4e5f maxLength: 32 minLength: 32 type: string failureCategory: description: Why a REJECTED attempt failed. Present only on REJECTED, and only when a cause was recorded. Only REJECTED_BY_RAIL implies the order reached the rail. enum: - INSUFFICIENT_FUNDS - INSUFFICIENT_LIMIT - OPERATIONAL_FAILURE - REJECTED_BY_RAIL examples: - INSUFFICIENT_FUNDS type: string outcome: description: Outcome of the latest settlement attempt. PROCESSING while the order is being placed or the rail has not answered; COMPLETED once the money moved; REJECTED when the attempt failed (failureCategory says why, when recorded); UNKNOWN when the order was dispatched and its fate is not yet known. enum: - PROCESSING - COMPLETED - REJECTED - UNKNOWN examples: - COMPLETED type: string startedAt: description: When the attempt was recorded, before the order was sent. RFC 3339, UTC. examples: - "2026-09-10T12:00:01Z" format: date-time type: string required: - outcome - endToEndId - startedAt type: object ScheduledPaymentUnblockBody: additionalProperties: false properties: actorId: description: Identifier of the human operator requesting the release. It does not influence the decision and the response does not return it. examples: - ops-maria maxLength: 120 type: string overrideReason: description: Why the operator is intervening. It does not influence the decision, which rests on what the SPI answers, and the response does not return it. examples: - settlement stuck since the morning window maxLength: 200 type: string overrideTicket: description: Ticket the intervention is recorded under in your own system. It does not influence the decision and the response does not return it. examples: - OPS-4711 maxLength: 60 type: string type: object ScheduledPaymentUnblockResponse: additionalProperties: false properties: evidence: description: "Which proof permitted the unblock. NOTHING_SENT: no settlement attempt was ever filed under the claim, so nothing was sent. NOT_ON_RAIL: an attempt was filed, and the SPI has no transfer for its identifier. RAIL_REJECTED: the SPI rejected the order and the ledger entry was reverted." enum: - NOTHING_SENT - NOT_ON_RAIL - RAIL_REJECTED examples: - NOT_ON_RAIL type: string releasedOperationId: description: Execution operation that was holding the debit. examples: - settlement-dispatch-2026-09-10-org-a type: string scheduledPaymentId: description: Internal identifier of the scheduled debit whose claim was released. examples: - 0198f3a2-1c4e-7c8b-9d1e-2f3a4b5c6d40 format: uuid type: string status: description: Lifecycle status the debit holds after the unblock. It returns to SCHEDULED, which is what makes it eligible for a further settlement attempt. examples: - SCHEDULED type: string unblockedAt: description: Instant Pix Lerian released the claim, in UTC. It is Pix Lerian's own clock reading, not a value from the request. examples: - "2026-09-10T14:00:00Z" format: date-time type: string required: - scheduledPaymentId - status - releasedOperationId - evidence - unblockedAt type: object securitySchemes: BearerAuth: bearerFormat: JWT description: JWT bearer token issued by the identity provider. scheme: bearer type: http 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 openapi: 3.1.0 paths: /payer/authorization-requests: get: description: |- Returns the requests still awaiting the payer's decision, newest first — the "consulta e gerenciamento de autorizações pendentes" of Guia v1.2 §6.4. A request LEAVES this list when it is accepted, rejected, cancelled by the receiving PSP (pain.011) or expires: §3.2 requires the payer PSP to remove it in the last two cases. There is deliberately no status parameter to widen the surface with. This page is a lifecycle projection: it carries identifiers, journey, status and deadlines, but not the counterparty or recurrence terms. The channel must obtain the terms it displays to the payer from its provider/messaging integration. Paging is by cursor. On the last page next_cursor is null, never an empty string. operationId: listPayerAuthorizationRequests 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: Maximum number of records per page (1-100, default 10). A value outside that range, or one that is not an integer, is REFUSED — never clamped, never silently coerced. example: 25 explode: false in: query name: limit schema: default: 10 format: int64 maximum: 100 minimum: 1 type: integer - description: Opaque cursor taken from a previous page's next_cursor. On the last page that value is null, never an empty string. A malformed or undecodable value is refused with 400. The cursor must be replayed against the same endpoint, with the same sort_order and the same filters used to obtain it; changing any of those starts a different query, and the previous cursor should not be reused. explode: false in: query name: cursor schema: description: Opaque cursor taken from a previous page's next_cursor. On the last page that value is null, never an empty string. A malformed or undecodable value is refused with 400. The cursor must be replayed against the same endpoint, with the same sort_order and the same filters used to obtain it; changing any of those starts a different query, and the previous cursor should not be reused. examples: - eyJ0IjoiMjAyNi0wOC0yN1QxODo0MjowMFoiLCJpIjoiMDE5OGYzYTEtN2M0Mi03ZGUxLWEwMjQtYjFmMGI3ZTljMzAxIn0= type: string - description: Sort direction. An unrecognised value is refused rather than silently defaulted, because switching it mid-traversal without notice would silently reverse the page sequence the caller is walking. explode: false in: query name: sort_order schema: default: desc description: Sort direction. An unrecognised value is refused rather than silently defaulted, because switching it mid-traversal without notice would silently reverse the page sequence the caller is walking. enum: - asc - desc examples: - desc type: string responses: "200": content: application/json: example: items: - authorizationRequestId: SC12345678202608276bca619e690 expiresAt: "2026-09-26T19:18:38Z" journey: JOURNEY_2 receivedAt: "2026-08-27T19:18:38Z" recurrenceId: RR12345678202608276bca619e690 status: RECEIVED next_cursor: null prev_cursor: null schema: $ref: "#/components/schemas/AuthorizationRequestPage" description: A page of pending authorization requests. "400": content: application/json: schema: $ref: "#/components/schemas/Error" description: Malformed or invalid path, header or query input (PIX-0001, PIX-0003, PIX-0015, PIX-0017, PIX-0020, plus operation-specific PIX codes). "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." "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. 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. summary: List authorization requests pending the payer's decision tags: - Payer Authorization Requests x-mint: href: /pt/reference/interfaces/pix-lerian/pix-automatico/list-authorization-requests /payer/authorization-requests/from-qr: post: 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. 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. "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." summary: Load a recurrence from a scanned QR Code tags: - Payer Authorization Requests x-mint: href: /pt/reference/interfaces/pix-lerian/pix-automatico/create-authorization-request-from-qr-code /payer/authorization-requests/{authorization_request_id}: get: description: |- Returns one authorization request, in ANY state: pending, accepted, rejected, cancelled by the receiving PSP or expired. It is the companion of the pending-request listing above, which a request LEAVES the moment it is decided (Guia v1.2 §3.2) — this operation is what an integrator calls afterwards to learn the outcome. A request belonging to a different account than X-Account-Id names is answered 404, exactly as one that does not exist: the account is a predicate on the lookup, so this end never learns the request exists elsewhere and cannot confirm it. operationId: getPayerAuthorizationRequest 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: Payer-side request identifier, in ANY state — pending or already decided. It is the counterparty idSolicRec on journey 1 and a local identifier on QR journeys. Fixed 29-character shape (Manual de Padrões §2.2.1); one that does not parse into a well-formed identifier is refused with 422 (PIX-0810). 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 request identifier, in ANY state — pending or already decided. It is the counterparty idSolicRec on journey 1 and a local identifier on QR journeys. Fixed 29-character shape (Manual de Padrões §2.2.1); one that does not parse into a well-formed identifier is refused with 422 (PIX-0810). 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 maxLength: 29 minLength: 29 pattern: ^SC[0-9A-Z]{8}[0-9]{8}[a-zA-Z0-9]{11}$ type: string responses: "200": content: application/json: examples: accepted: summary: Accepted -- decided and carrying decidedAt value: authorizationRequestId: SC12345678202608276bca619e690 decidedAt: "2026-08-27T19:20:00Z" expiresAt: "2026-09-26T19:18:38Z" receivedAt: "2026-08-27T19:18:38Z" recurrenceId: RR12345678202608276bca619e690 status: ACCEPTED journey: JOURNEY_1 pending: summary: Pending -- not yet decided, so neither field is published value: authorizationRequestId: SC12345678202608276bca619e690 expiresAt: "2026-09-26T19:18:38Z" receivedAt: "2026-08-27T19:18:38Z" recurrenceId: RR12345678202608276bca619e690 status: RECEIVED journey: JOURNEY_1 rejected: summary: Rejected -- decided, carrying decidedAt and rejectionReason value: authorizationRequestId: SC12345678202608276bca619e690 decidedAt: "2026-08-27T19:20:00Z" expiresAt: "2026-09-26T19:18:38Z" receivedAt: "2026-08-27T19:18:38Z" recurrenceId: RR12345678202608276bca619e690 rejectionReason: RejectedByDebtor status: REJECTED journey: JOURNEY_1 schema: $ref: "#/components/schemas/AuthorizationRequestItem" description: The authorization request, in any state. "400": content: application/json: schema: $ref: "#/components/schemas/Error" description: Malformed or invalid path, header or query input (PIX-0001, PIX-0003, PIX-0015, PIX-0017, PIX-0020, plus operation-specific PIX codes). "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." "404": content: application/json: schema: $ref: "#/components/schemas/Error" description: No authorization request with that id is reachable by the caller (PIX-0800). "422": content: application/json: schema: $ref: "#/components/schemas/Error" description: authorization_request_id parsed as a path segment but does not match the 29-character idSolicRec format of Manual de Padrões §2.2.1 (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. 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. summary: Get one authorization request tags: - Payer Authorization Requests x-mint: href: /pt/reference/interfaces/pix-lerian/pix-automatico/get-authorization-request /payer/authorization-requests/{authorization_request_id}/decide: post: 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. On the QR Code journeys (2, 3 and 4) a rejection is recorded but not communicated to the counterparty at all: the BACEN defines no rejection message for them (Manual de Padrões para Iniciação do Pix v2.9.0 §3.1). 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 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." "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), when one is owed, 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-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." "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). Also PIX-0809 when an ACCEPT finds a mandate already granted over the same recurrence, so no second one is created." "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. 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. summary: Accept or reject an authorization request tags: - Payer Authorization Requests x-mint: href: /pt/reference/interfaces/pix-lerian/pix-automatico/decide-authorization-request /payer/authorizations: get: description: |- Returns the payer's mandates. Without include_terminated it answers the ones that have NOT ENDED — the APPROVED mandates and those still AWAITING_CONCLUSION — which is the "consulta e gerenciamento de autorizações ativas" surface of Guia v1.2 §6.4; with include_terminated=true it answers that same section's "histórico de autorizações", the REJECTED, EXPIRED and CANCELLED mandates included. WARNING: THE DEFAULT PAGE IS NOT THE SET OF ACTIVE MANDATES. A mandate stays AWAITING_CONCLUSION until the receiving PSP answers this end's concession with its conclusive pain.012, and until that message arrives it is NOT active at BACEN: nothing may be debited under it (Manual de Tempos do Pix v7.0 §3.2). It is listed by default because the payer was told to wait for precisely that flow and would look for it here. Filter on status=APPROVED to read only the mandates that are in force. The maximum amount is returned here because this is the PAYER's own authenticated channel. Guia v1.2 §6.1 bars sharing it with the RECEIVING user and their PSP, which this surface is not. This page does not repeat the counterparty or complete recurrence terms. It is the lifecycle and payer-parameter projection; the channel must join any richer display data from its provider/messaging integration. Paging is by cursor. On the last page next_cursor is null, never an empty string. operationId: listPayerAuthorizations 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: Maximum number of records per page (1-100, default 10). A value outside that range, or one that is not an integer, is REFUSED — never clamped, never silently coerced. example: 25 explode: false in: query name: limit schema: default: 10 format: int64 maximum: 100 minimum: 1 type: integer - description: Opaque cursor taken from a previous page's next_cursor. On the last page that value is null, never an empty string. A malformed or undecodable value is refused with 400. The cursor must be replayed against the same endpoint, with the same sort_order and the same filters used to obtain it; changing any of those starts a different query, and the previous cursor should not be reused. explode: false in: query name: cursor schema: description: Opaque cursor taken from a previous page's next_cursor. On the last page that value is null, never an empty string. A malformed or undecodable value is refused with 400. The cursor must be replayed against the same endpoint, with the same sort_order and the same filters used to obtain it; changing any of those starts a different query, and the previous cursor should not be reused. examples: - eyJ0IjoiMjAyNi0wOC0yN1QxODo0MjowMFoiLCJpIjoiMDE5OGYzYTEtN2M0Mi03ZGUxLWEwMjQtYjFmMGI3ZTljMzAxIn0= type: string - description: Sort direction. An unrecognised value is refused rather than silently defaulted, because switching it mid-traversal without notice would silently reverse the page sequence the caller is walking. explode: false in: query name: sort_order schema: default: desc description: Sort direction. An unrecognised value is refused rather than silently defaulted, because switching it mid-traversal without notice would silently reverse the page sequence the caller is walking. enum: - asc - desc examples: - desc type: string - description: "Filter by the MANDATE's lifecycle status, the vocabulary each item's status field carries: AWAITING_CONCLUSION, APPROVED, REJECTED, EXPIRED, CANCELLED. To filter on several, send them as ONE comma-separated value (status=APPROVED,CANCELLED): repeating the parameter is not supported, and only its first occurrence is read. A status this end does not know matches no row, which is an empty page rather than an error." explode: false in: query name: status schema: description: "Filter by the MANDATE's lifecycle status, the vocabulary each item's status field carries: AWAITING_CONCLUSION, APPROVED, REJECTED, EXPIRED, CANCELLED. To filter on several, send them as ONE comma-separated value (status=APPROVED,CANCELLED): repeating the parameter is not supported, and only its first occurrence is read. A status this end does not know matches no row, which is an empty page rather than an error." examples: - - APPROVED items: type: string type: - array - "null" - description: Include the mandates that have ENDED — REJECTED, EXPIRED and CANCELLED — which is the full "histórico de autorizações" surface of Guia v1.2 §6.4. Absent, the page carries only the mandates that have not ended, AWAITING_CONCLUSION among them. explode: false in: query name: include_terminated schema: default: false description: Include the mandates that have ENDED — REJECTED, EXPIRED and CANCELLED — which is the full "histórico de autorizações" surface of Guia v1.2 §6.4. Absent, the page carries only the mandates that have not ended, AWAITING_CONCLUSION among them. examples: - true type: boolean responses: "200": content: application/json: example: items: - authorizedAt: "2026-08-27T19:18:38Z" createdAt: "2026-08-27T19:18:38Z" id: 01a044a8-f3bd-7488-a0dc-e8d4be4802be journey: JOURNEY_1 parameters: creditLineEnabled: false maximumAmount: amount: "250.75" currency: BRL schedulingNotificationsEnabled: false recurrenceId: RR12345678202608276bca619e690 status: APPROVED updatedAt: "2026-08-27T19:20:00Z" next_cursor: null prev_cursor: null schema: $ref: "#/components/schemas/AuthorizationPage" description: A page of authorizations. "400": content: application/json: schema: $ref: "#/components/schemas/Error" description: Malformed or invalid path, header or query input (PIX-0001, PIX-0003, PIX-0015, PIX-0017, PIX-0020, plus operation-specific PIX codes). "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." "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. 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. "422": content: application/json: schema: $ref: "#/components/schemas/Error" description: Unprocessable Entity summary: List the payer's authorizations tags: - Payer Authorizations x-mint: href: /pt/reference/interfaces/pix-lerian/pix-automatico/list-authorizations /payer/authorizations/{authorization_id}: get: description: |- Returns one mandate, in ANY lifecycle state Authorizations itself lists: AWAITING_CONCLUSION, APPROVED, REJECTED, EXPIRED or CANCELLED. The representation is the SAME AuthorizationItem the listing already publishes. A mandate belonging to a different account than X-Account-Id names is answered 404, exactly as one that does not exist: the account is a predicate on the lookup, so this end never learns the mandate exists elsewhere and cannot confirm it. This operation does not include history: an integrator reads the append-only audit through the /history route. operationId: getPayerAuthorization 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: Internal identifier of the mandate, in ANY lifecycle state. A 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_id required: true schema: description: Internal identifier of the mandate, in ANY lifecycle state. A mandate under a different X-Account-Id is answered 404, not 403, so the caller cannot confirm that a resource exists elsewhere. examples: - 01a044a8-f3bd-7488-a0dc-e8d4be4802be type: string responses: "200": content: application/json: example: authorizedAt: "2026-08-27T19:18:38Z" createdAt: "2026-08-27T19:18:38Z" id: 01a044a8-f3bd-7488-a0dc-e8d4be4802be journey: JOURNEY_1 parameters: creditLineEnabled: false maximumAmount: amount: "250.75" currency: BRL schedulingNotificationsEnabled: false recurrenceId: RR12345678202608276bca619e690 status: APPROVED updatedAt: "2026-08-27T19:20:00Z" schema: $ref: "#/components/schemas/AuthorizationItem" description: The authorization. "400": content: application/json: schema: $ref: "#/components/schemas/Error" description: Malformed or invalid path, header or query input (PIX-0001, PIX-0003, PIX-0015, PIX-0017, PIX-0020, plus operation-specific PIX codes). "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." "404": content: application/json: schema: $ref: "#/components/schemas/Error" description: No authorization with that identifier is reachable by the caller (PIX-0804). "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. 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. summary: Get one authorization tags: - Payer Authorizations x-mint: href: /pt/reference/interfaces/pix-lerian/pix-automatico/get-authorization patch: description: |- RFC 7386 JSON Merge Patch over the three payer-configurable parameters of Guia v1.2 §6. Setting a property to null resets it to its NORMATIVE default; omitting it leaves it unchanged. The two toggles default to enabled, so a reset is not an opt-out. A change never reaches debits already scheduled. The maximum amount in force at scheduling time is snapshotted on the debit and prevails (Guia v1.2 §6.1); the new value applies to future scheduling only. The maximum amount never leaves this PSP: it is not shared with the receiving user or their PSP (Guia v1.2 §6.1). On an authorization whose recurrence was created via the Open Finance track, the maximum amount is NOT editable here: the payer sets it once, when requesting the consent in the initiator's environment (Guia v1.2 §6.1). A patch carrying that key -- with a value or with null -- is refused with PIX-0812 and nothing is written. The scheduling notification and credit line parameters remain editable on those authorizations, so send the patch without the maximum amount key. operationId: updatePayerAuthorizationParameters 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: "Internal identifier of the mandate whose parameters are being changed. A request or mandate that exists under a DIFFERENT account than X-Account-Id names is answered 404, not 403: the lookup carries the account as a predicate, so this end never learns that a resource exists elsewhere and cannot confirm it." in: path name: authorization_id required: true schema: description: "Internal identifier of the mandate whose parameters are being changed. A request or mandate that exists under a DIFFERENT account than X-Account-Id names is answered 404, not 403: the lookup carries the account as a predicate, so this end never learns that a resource exists elsewhere and cannot confirm it." examples: - 01a044a8-f3bd-7488-a0dc-e8d4be4802be type: string requestBody: content: application/merge-patch+json: examples: change-parameters: summary: Change payer-controlled parameters value: creditLineEnabled: false maximumAmount: amount: "250.00" currency: BRL schedulingNotificationsEnabled: false restore-defaults: summary: Restore every parameter to its normative default value: creditLineEnabled: null maximumAmount: null schedulingNotificationsEnabled: null schema: $ref: "#/components/schemas/AuthorizationParametersPatch" description: The merge-patch document. Every property is optional, and null is meaningful on all three. required: true responses: "200": content: application/json: example: authorizedAt: "2026-08-27T19:18:38Z" createdAt: "2026-08-27T19:18:38Z" id: 01a044a8-f3bd-7488-a0dc-e8d4be4802be journey: JOURNEY_1 parameters: creditLineEnabled: false maximumAmount: amount: "250.00" currency: BRL schedulingNotificationsEnabled: false recurrenceId: RR12345678202608276bca619e690 status: APPROVED updatedAt: "2026-08-27T19:20:00Z" schema: $ref: "#/components/schemas/AuthorizationParametersResponse" description: Parameters updated. The body carries the three parameters as they now stand. "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-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." "404": content: application/json: schema: $ref: "#/components/schemas/Error" description: No authorization with that identifier is reachable by the caller (PIX-0804). "409": content: application/json: schema: $ref: "#/components/schemas/Error" description: "The authorization is not in a state that accepts parameter changes (PIX-0805), or the patch edits the maximum amount of an authorization whose recurrence was created on the Open Finance track, where that value is set in the initiator's environment (PIX-0812). PIX-0812 refuses the maximum amount alone: the same request without that key succeeds, and the other two parameters stay editable." "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 non-empty body used neither the canonical application/merge-patch+json media type nor the application/json compatibility form (PIX-0016). The legacy error message names application/json; new clients should send application/merge-patch+json. "422": content: application/json: schema: $ref: "#/components/schemas/Error" description: "The maximum amount is admissible in isolation but not against this mandate: it sits below the recurrence floor or below its fixed amount (PIX-0806, PIX-0811)." "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. 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. summary: Update the payer-configurable parameters of an authorization tags: - Payer Authorizations x-mint: href: /pt/reference/interfaces/pix-lerian/pix-automatico/update-authorization-parameters /payer/authorizations/{authorization_id}/cancel: post: description: |- Revokes the mandate at the payer's request. The revocation is IMMEDIATE and CASCADES over every debit scheduled under it, retries after the due date included — except those due for settlement on the day the revocation happens, which are preserved by rule (Guia v1.2 §3.7.1). The termination and the scheduled-debit cascade commit together or not at all, so a mandate cannot be revoked while cancellable debits remain active. A non-zero preservedScheduledPayments is CORRECT behaviour, not a partial failure. Those debits will still settle today, and the payer is shown the count so they know it. The body's reason is a free-text note for the payer's own audit trail. It is NOT the value sent to the counterparty: the receiving PSP is told motivoCancelamento = SLDB, the pain.011 code for a cancellation the paying user asked for, which the response echoes as counterpartyReason. A revocation over a mandate that has upcoming debits reports non-zero values on either counter, so a caller must read them rather than assume zero. operationId: cancelPayerAuthorization 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: "Internal identifier of the mandate being revoked. A request or mandate that exists under a DIFFERENT account than X-Account-Id names is answered 404, not 403: the lookup carries the account as a predicate, so this end never learns that a resource exists elsewhere and cannot confirm it." in: path name: authorization_id required: true schema: description: "Internal identifier of the mandate being revoked. A request or mandate that exists under a DIFFERENT account than X-Account-Id names is answered 404, not 403: the lookup carries the account as a predicate, so this end never learns that a resource exists elsewhere and cannot confirm it." examples: - 01a044a8-f3bd-7488-a0dc-e8d4be4802be type: string requestBody: content: application/json: examples: payer-request: summary: Cancel at the payer's request value: reason: Payer requested revocation in the mobile app schema: $ref: "#/components/schemas/AuthorizationCancellationBody" description: Optional. Carries the payer's own free-text note, which is never forwarded to the counterparty. responses: "200": content: application/json: example: authorizationId: 01a044a8-f3bd-7488-a0dc-e8d4be4802be cancelledScheduledPayments: 0 counterpartyReason: SLDB preservedScheduledPayments: 0 status: CANCELLED schema: $ref: "#/components/schemas/AuthorizationCancellationResponse" 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." "202": content: application/json: example: authorizationId: 01a044a8-f3bd-7488-a0dc-e8d4be4802be cancelledScheduledPayments: 0 counterpartyReason: SLDB preservedScheduledPayments: 0 status: CANCELLED schema: $ref: "#/components/schemas/AuthorizationCancellationResponse" description: Authorization revoked and cascade applied. Both counters are facts about the same commit. "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-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." "404": content: application/json: schema: $ref: "#/components/schemas/Error" description: No authorization with that identifier is reachable by the caller (PIX-0804). "409": content: application/json: schema: $ref: "#/components/schemas/Error" description: The authorization is already terminated (PIX-0805). "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). "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. 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. summary: Cancel an authorization at the payer's request tags: - Payer Authorizations x-mint: href: /pt/reference/interfaces/pix-lerian/pix-automatico/cancel-authorization /payer/authorizations/{authorization_id}/history: get: description: |- Returns the append-only audit of one mandate: previous state, new state, instant, actor, correlation, and the operation identifier when the transition came from an external invocation. The projection is never updated and never deleted from. Ordering is by the instant the transition HAPPENED (occurredAt), which is also what the cursor resumes on — not the write instant. A mandate belonging to another payer account is answered 404, exactly as one that does not exist: the account in X-Account-Id is a predicate on the lookup, so this end never learns the mandate exists elsewhere and cannot confirm it. Paging is by cursor. On the last page next_cursor is null, never an empty string. operationId: listPayerAuthorizationHistory 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: Maximum number of records per page (1-100, default 10). A value outside that range, or one that is not an integer, is REFUSED — never clamped, never silently coerced. example: 25 explode: false in: query name: limit schema: default: 10 format: int64 maximum: 100 minimum: 1 type: integer - description: Opaque cursor taken from a previous page's next_cursor. On the last page that value is null, never an empty string. A malformed or undecodable value is refused with 400. The cursor must be replayed against the same endpoint, with the same sort_order and the same filters used to obtain it; changing any of those starts a different query, and the previous cursor should not be reused. explode: false in: query name: cursor schema: description: Opaque cursor taken from a previous page's next_cursor. On the last page that value is null, never an empty string. A malformed or undecodable value is refused with 400. The cursor must be replayed against the same endpoint, with the same sort_order and the same filters used to obtain it; changing any of those starts a different query, and the previous cursor should not be reused. examples: - eyJ0IjoiMjAyNi0wOC0yN1QxODo0MjowMFoiLCJpIjoiMDE5OGYzYTEtN2M0Mi03ZGUxLWEwMjQtYjFmMGI3ZTljMzAxIn0= type: string - description: Sort direction. An unrecognised value is refused rather than silently defaulted, because switching it mid-traversal without notice would silently reverse the page sequence the caller is walking. explode: false in: query name: sort_order schema: default: desc description: Sort direction. An unrecognised value is refused rather than silently defaulted, because switching it mid-traversal without notice would silently reverse the page sequence the caller is walking. enum: - asc - desc examples: - desc type: string - description: "Internal identifier of the mandate whose transitions are being read. A request or mandate that exists under a DIFFERENT account than X-Account-Id names is answered 404, not 403: the lookup carries the account as a predicate, so this end never learns that a resource exists elsewhere and cannot confirm it." in: path name: authorization_id required: true schema: description: "Internal identifier of the mandate whose transitions are being read. A request or mandate that exists under a DIFFERENT account than X-Account-Id names is answered 404, not 403: the lookup carries the account as a predicate, so this end never learns that a resource exists elsewhere and cannot confirm it." examples: - 01a044a8-f3bd-7488-a0dc-e8d4be4802be type: string responses: "200": content: application/json: example: items: - actor: PAYER id: 01a044a8-f3bd-7d16-b8d9-6a5cf0319996 newStatus: AWAITING_CONCLUSION occurredAt: "2026-08-27T19:18:38Z" - actor: RECEIVER_PSP id: 01a044a8-f4d6-76a1-aa32-a732ac2e8023 newStatus: APPROVED occurredAt: "2026-08-27T19:18:39Z" previousStatus: AWAITING_CONCLUSION next_cursor: null prev_cursor: null schema: $ref: "#/components/schemas/AuthorizationHistoryPage" description: A page of history entries. "400": content: application/json: schema: $ref: "#/components/schemas/Error" description: Malformed or invalid path, header or query input (PIX-0001, PIX-0003, PIX-0015, PIX-0017, PIX-0020, plus operation-specific PIX codes). "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." "404": content: application/json: schema: $ref: "#/components/schemas/Error" description: No authorization with that identifier exists on this end (PIX-0804). "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. 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. summary: List the state transitions of an authorization tags: - Payer Authorizations x-mint: href: /pt/reference/interfaces/pix-lerian/pix-automatico/list-authorization-history /payer/scheduled-payments: get: description: |- Returns the payer's scheduled-debit lifecycle for the account — the "consulta e gerenciamento de pagamentos agendados" of Guia v1.2 §6.4. It is NOT a forward-only view: a debit stays listed after it leaves SCHEDULED, so CANCELLED entries appear beside the ones still to come. A payer asking why a charge did not happen needs the cancelled row, and the cancellation route needs the id only this listing returns. The status keeps the scheduling lifecycle and does NOT report the payment: a debit that settled keeps reading SCHEDULED. The settlement carries the payment outcome, read from the debit's LATEST settlement attempt — outcome PROCESSING while the order is in flight, COMPLETED once the money moved, REJECTED (with failureCategory when a cause was recorded) or UNKNOWN when the order was dispatched and its fate is not yet known — together with the attempt's endToEndId, startedAt and, once COMPLETED or REJECTED, concludedAt. settlement is absent while the debit has no attempt. When a read replica is configured, an attempt that has just concluded can still read PROCESSING for a moment. The settlement_* events push only negative or pending outcomes; a COMPLETED settlement emits no event and is seen only by re-reading this listing (or the account's outgoing Pix). An empty page means that the account named in X-Account-Id has no scheduled debit. This is the ONLY operation that returns a scheduled debit's id, and POST /v1/payer/scheduled-payments/{scheduled_payment_id}/cancel needs that id. Integrate the two together: list, then cancel by the id an item carries. Each item carries maximumAmountSnapshot — the ceiling in force when the debit was SCHEDULED, written once and never updated — so a payer who has since changed the ceiling can see why an existing debit still reflects the old one. Returning it here is the payer's own authenticated channel; Guia v1.2 §6.1 bars sharing it with the RECEIVING user and their PSP, which this surface is not. Ordering is by scheduledDate and then by id, which is also what the cursor resumes on — not the write instant, unlike the three sibling listings. authorizationId is absent on a debit scheduled without a mandate (purpose RIFL), and maximumAmountSnapshot is absent when no ceiling was in force; neither absence is an error. Paging is by cursor. On the last page next_cursor is null, never an empty string. operationId: listPayerScheduledPayments 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: Maximum number of records per page (1-100, default 10). A value outside that range, or one that is not an integer, is REFUSED — never clamped, never silently coerced. example: 25 explode: false in: query name: limit schema: default: 10 format: int64 maximum: 100 minimum: 1 type: integer - description: Opaque cursor taken from a previous page's next_cursor. On the last page that value is null, never an empty string. A malformed or undecodable value is refused with 400. The cursor must be replayed against the same endpoint, with the same sort_order and the same filters used to obtain it; changing any of those starts a different query, and the previous cursor should not be reused. explode: false in: query name: cursor schema: description: Opaque cursor taken from a previous page's next_cursor. On the last page that value is null, never an empty string. A malformed or undecodable value is refused with 400. The cursor must be replayed against the same endpoint, with the same sort_order and the same filters used to obtain it; changing any of those starts a different query, and the previous cursor should not be reused. examples: - eyJ0IjoiMjAyNi0wOC0yN1QxODo0MjowMFoiLCJpIjoiMDE5OGYzYTEtN2M0Mi03ZGUxLWEwMjQtYjFmMGI3ZTljMzAxIn0= type: string - description: Sort direction. An unrecognised value is refused rather than silently defaulted, because switching it mid-traversal without notice would silently reverse the page sequence the caller is walking. explode: false in: query name: sort_order schema: default: desc description: Sort direction. An unrecognised value is refused rather than silently defaulted, because switching it mid-traversal without notice would silently reverse the page sequence the caller is walking. enum: - asc - desc examples: - desc type: string responses: "200": content: application/json: example: items: - amount: amount: "149.95" currency: BRL createdAt: "2026-10-01T12:00:00Z" id: 0198f3a2-1c4e-7c8b-9d1e-2f3a4b5c6d41 purpose: AGND recurrenceId: RN12345678202608101a2b3c4d5e6 scheduledDate: "2026-10-10" status: SCHEDULED updatedAt: "2026-10-01T12:00:00Z" - amount: amount: "149.95" currency: BRL createdAt: "2026-09-01T12:00:00Z" id: 0198f3a2-1c4e-7c8b-9d1e-2f3a4b5c6d40 purpose: AGND recurrenceId: RN12345678202608101a2b3c4d5e6 scheduledDate: "2026-09-10" settlement: concludedAt: "2026-09-10T12:00:04Z" endToEndId: E12345678202609101200a1b2c3d4e5f outcome: COMPLETED startedAt: "2026-09-10T12:00:01Z" status: SCHEDULED updatedAt: "2026-09-01T12:00:00Z" next_cursor: eyJ0IjoiMjAyNi0wOS0xMCIsImkiOiIwMTk4ZjNhMi0xYzRlLTdjOGItOWQxZS0yZjNhNGI1YzZkNDAifQ== prev_cursor: null schema: $ref: "#/components/schemas/ScheduledPaymentPage" description: A page of scheduled debits, newest settlement date first. Empty when the account named in X-Account-Id has none. "400": content: application/json: schema: $ref: "#/components/schemas/Error" description: Malformed or invalid path, header or query input (PIX-0001, PIX-0003, PIX-0015, PIX-0017, PIX-0020, plus operation-specific PIX codes). "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." "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. 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. summary: List scheduled debits tags: - Payer Scheduled Payments x-mint: href: /pt/reference/interfaces/pix-lerian/pix-automatico/list-scheduled-payments /payer/scheduled-payments/{scheduled_payment_id}/cancel: post: description: |- Cancels ONE scheduled debit at the payer's request (Guia v1.2 §4.1). The AUTHORIZATION IS NOT AFFECTED. This stops a single charge; the mandate keeps billing and future cycles are still scheduled. To end the mandate itself — which cascades over every debit scheduled under it — use POST /v1/payer/authorizations/{authorization_id}/cancel instead. The two are told apart on the wire by the camt.055 reason: SLBD here, CCLD there. THE WINDOW CLOSES AT MIDNIGHT of the settlement date, in America/Sao_Paulo: the payer may cancel up to 23:59:59 of the day before, and a request at or after 00:00 is refused with PIX-0825. That boundary is where the 00:00-08:00 settlement window opens, so a cancellation admitted past it would race the debit it is trying to stop. A DEBIT ARISING FROM A POST-DUE RETRY (purpose NTAG) CANNOT BE CANCELLED HERE, at any hour, and is refused with PIX-0826 (Guia v1.2 §5.1): the retry is a collection the payer already authorized, and ending the mandate is the payer's remedy. The receiving side may still cancel that same charge. The cancellation is communicated to the receiving PSP by camt.055, raised asynchronously from an obligation written in the same transaction as the cancellation. The payer is notified of the cancellation unconditionally, including when scheduling notifications are disabled. operationId: cancelPayerScheduledPayment 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: "Internal identifier of the scheduled debit being cancelled. A debit that exists under a DIFFERENT account than X-Account-Id names is answered 404, not 403: the lookup carries the account as a predicate, so this end never learns that a debit exists elsewhere and cannot confirm it." in: path name: scheduled_payment_id required: true schema: description: "Internal identifier of the scheduled debit being cancelled. A debit that exists under a DIFFERENT account than X-Account-Id names is answered 404, not 403: the lookup carries the account as a predicate, so this end never learns that a debit exists elsewhere and cannot confirm it." examples: - 0198f3a2-1c4e-7c8b-9d1e-2f3a4b5c6d40 format: uuid type: string responses: "200": content: application/json: example: amount: "149.90" cancelledAt: "2026-09-09T15:00:00Z" counterpartyReason: SLBD endToEndId: E1234567820260810120011a2b3c4d5e scheduledDate: "2026-09-10" scheduledPaymentId: 0198f3a2-1c4e-7c8b-9d1e-2f3a4b5c6d40 status: CANCELLED schema: $ref: "#/components/schemas/ScheduledPaymentCancellationResponse" 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." "202": content: application/json: example: amount: "149.90" cancelledAt: "2026-09-09T15:00:00Z" counterpartyReason: SLBD endToEndId: E1234567820260810120011a2b3c4d5e scheduledDate: "2026-09-10" scheduledPaymentId: 0198f3a2-1c4e-7c8b-9d1e-2f3a4b5c6d40 status: CANCELLED schema: $ref: "#/components/schemas/ScheduledPaymentCancellationResponse" description: Scheduled debit cancelled. The camt.055 that tells the counterparty is raised asynchronously from an obligation committed with the cancellation. "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-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." "404": content: application/json: schema: $ref: "#/components/schemas/Error" description: No scheduled debit with that identifier is reachable by the caller (PIX-0824). "409": content: application/json: schema: $ref: "#/components/schemas/Error" description: The debit can no longer be cancelled — the cutoff has passed or it is no longer scheduled (PIX-0825) — or it arose from a post-due retry, which this channel never cancels (PIX-0826). "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). "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. 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. summary: Cancel a single scheduled debit at the payer's request tags: - Payer Scheduled Payments x-mint: href: /pt/reference/interfaces/pix-lerian/pix-automatico/cancel-scheduled-payment /payer/scheduled-payments/{scheduled_payment_id}/unblock: post: description: |- Releases the settlement claim on ONE scheduled debit whose settlement attempt went out and never got an outcome, so the debit becomes eligible for a further attempt. THE SPI DECIDES, NOT THE CALLER. The request has no field to state what happened. Pix Lerian releases the debit only when nothing was sent, or when the SPI has no record of the attempt or rejected it and the ledger entry was reverted. Any other answer refuses the release with PIX-0827, including when the SPI cannot be asked. The attempt must be at least 2 minutes old. The response names which of the three cases applied. NOTHING IS CANCELLED. The charge, the schedule and the authorization stay as they are, and the receiving PSP is told nothing. To stop a charge, use POST /v1/payer/scheduled-payments/{scheduled_payment_id}/cancel instead. The caller needs the scheduled-payment-recovery permission with the post action. The permission that allows the cancel operation does not grant it. operationId: unblockPayerScheduledPayment 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: "Internal identifier of the scheduled debit whose settlement claim is to be released. A debit that exists under a DIFFERENT account than X-Account-Id names is answered 404, not 403: the lookup carries the account as a predicate, so this end never learns that a debit exists elsewhere." in: path name: scheduled_payment_id required: true schema: description: "Internal identifier of the scheduled debit whose settlement claim is to be released. A debit that exists under a DIFFERENT account than X-Account-Id names is answered 404, not 403: the lookup carries the account as a predicate, so this end never learns that a debit exists elsewhere." examples: - 0198f3a2-1c4e-7c8b-9d1e-2f3a4b5c6d40 format: uuid type: string requestBody: content: application/json: examples: operator-intervention: summary: Release a debit whose order never reached the SPI value: actorId: ops-maria overrideReason: settlement stuck since the morning window overrideTicket: OPS-4711 schema: $ref: "#/components/schemas/ScheduledPaymentUnblockBody" description: Optional. Carries the operator attribution. Pix Lerian does not use it to decide the release. responses: "200": content: application/json: example: evidence: NOT_ON_RAIL releasedOperationId: settlement-dispatch-2026-09-10-org-a scheduledPaymentId: 0198f3a2-1c4e-7c8b-9d1e-2f3a4b5c6d40 status: SCHEDULED unblockedAt: "2026-09-10T14:00:00Z" schema: $ref: "#/components/schemas/ScheduledPaymentUnblockResponse" description: Claim released. The debit is eligible again; nothing was cancelled and the receiving PSP was told nothing. "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-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." "404": content: application/json: schema: $ref: "#/components/schemas/Error" description: No scheduled debit with that identifier is reachable by the caller (PIX-0824). "409": content: application/json: schema: $ref: "#/components/schemas/Error" description: "The release is refused (PIX-0827). An entry in `errors` with location `detail` names the reason." "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). "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. 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. summary: Release the settlement claim on a stuck scheduled debit tags: - Payer Scheduled Payments x-mint: href: /pt/reference/interfaces/pix-lerian/pix-automatico/unblock-scheduled-payment security: - BearerAuth: [] servers: - url: https://api.example.com/pixauto/v1 description: Replace the example host with the URL provided during environment onboarding. 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, the cancellation of one of them, and the release of a debit whose settlement attempt never got an outcome. Cancelling a debit leaves the authorization ACTIVE — it stops one charge, not the mandate. The operations are meant to be used together: the listing is the only place a client receives the scheduled_payment_id the others address." name: Payer Scheduled Payments