Skip to main content
The Pix Automático API serves the payer side of recurring Pix payments. With it, the payer accepts or rejects an authorization request, manages the authorization, and cancels scheduled debits.

​
Call the API from your backend

The caller is your PSP backend, authenticated with an application token. The token identifies your application, not one of your customers. Your backend authenticates the payer and authorizes the payer for the account before it calls the API.
  • Send the payer account in X-Account-Id on account-scoped operations. Create authorization request from QR code takes the account in the payerAccountId body field instead.
  • A resource that belongs to a different account than the one you send returns 404.
  • Send X-Idempotency on each write. Reuse the value only to retry the same request.

​
Start an authorization from a QR code

  1. Call Create authorization request from QR code. Send the raw QR code content in qrCodePayload and the payer account in payerAccountId.
  2. The API decodes the QR code and detects the journey. It then resolves the payer account in the CRM and reads the recurrence payload from the receiving PSP over HTTPS.
  3. On journey 3, send immediatePayment.result as SETTLED. Also send immediatePayment.settlementConfirmedAt, the time your institution received the settlement confirmation. Without it, the API does not send an accepted authorization to BACEN. On journey 4, a FAILED result stops the journey.
  4. Keep the authorizationRequestId from the response. The request waits for the payer’s decision until expiresAt.
If the API cannot read the recurrence payload, the journey stops with an error and the API creates no request. If the CRM does not hold the payer account, the API answers 422 (PIX-0813). If the API cannot reach the CRM or has no CRM address, the API answers 503 (PIX-0814). On journey 1, the request comes from the receiving PSP. It also appears in the list of pending requests.

​
Decide a pending request

  1. Call List authorization requests to get the requests that wait for the payer’s decision. A request leaves this list when the payer accepts or rejects it, when the receiving PSP cancels it, or when it expires.
  2. Call Decide authorization request with decision set to ACCEPT or REJECT. Use the exact authorizationRequestId that the API returned.
  3. To accept, you can also send the payer parameters. A parameter that you do not send takes its default: notifications on, credit line on, and no maximum amount.
  4. To reject, send rejectionReason as NotRecognizedByDebtor or RejectedByDebtor.
  5. Call Get authorization request to read the outcome. It returns the request in any state.
The decision is a single command. There is no second confirmation step. The API sends the decision to the receiving PSP asynchronously. On journey 1, the receiving PSP does not answer a rejection. On journeys 2, 3, and 4, the API records a rejection and does not send it.

​
Manage authorizations

  • List authorizations returns the authorizations that have not ended: APPROVED and AWAITING_CONCLUSION. Send include_terminated=true to also get REJECTED, EXPIRED, and CANCELLED authorizations.
  • An AWAITING_CONCLUSION authorization is not active at BACEN until the receiving PSP concludes the process. Filter on status=APPROVED to get only the authorizations in force.
  • Get authorization returns one authorization in any state.
  • List authorization history returns the audit of state transitions. Each entry has the previous state, the new state, the time, and the actor.

​
Change the payer parameters

Update authorization parameters applies a JSON merge patch (RFC 7386) to the three payer parameters: maximumAmount, schedulingNotificationsEnabled, and creditLineEnabled. Send the body as application/merge-patch+json.
  • Omit a parameter to keep its value.
  • Set a parameter to null to reset it to its default. The two switches default to enabled, so a reset does not turn them off.
  • A change applies to debits that are scheduled after it. A debit that is already scheduled keeps the maximum amount that was in force when it was scheduled.
  • On an authorization created through Open Finance, the API refuses a change to maximumAmount with 409 (PIX-0812). The other two parameters stay editable.

​
Cancel an authorization

Cancel authorization ends the authorization at the payer’s request. The cancellation is immediate. It also cancels the debits scheduled under the authorization, including retries after the due date. Debits due for settlement on the day of the cancellation stay scheduled and settle that day. The response reports cancelledScheduledPayments and preservedScheduledPayments. A preserved count above zero is correct behavior, not a partial failure. The reason field is a free-text note for the payer’s audit trail. The receiving PSP gets the code SLDB, which the response returns in counterpartyReason. When the receiving PSP cancels the recurrence, the API also cancels the debits scheduled under it. It keeps the debits due on the day the cancellation arrives, and the next day’s debits when it arrives at or after 22:00 in the America/Sao_Paulo time zone. It also keeps a debit with a settlement attempt in any status other than REJECTED.

​
Cancel one scheduled debit

  1. Call List scheduled payments to get the identifier of the debit. This list also keeps cancelled debits. A settled debit keeps the status SCHEDULED, and its settlement block carries the payment outcome.
  2. Call Cancel scheduled payment with that identifier.
Cancelling one debit does not change the authorization. The authorization stays in force, and the next debits are still scheduled. To end the authorization, cancel the authorization. The API refuses the cancellation with 409 in these cases:
  • The request arrives at or after 00:00 on the settlement date, in the America/Sao_Paulo time zone (PIX-0825).
  • The debit comes from a retry after the due date, purpose NTAG (PIX-0826).
  • The debit is no longer SCHEDULED.
For the Pix Lerian request conventions, see Integrating with Pix Lerian.