Skip to navigation

Request a Pix Automático recurrence

Sends an authorization request to the payer’s bank. The payer approves it in their bank app; the result arrives as pix.automatic.recurrence.*. Requires the automatic_pix feature and the pix.automatic scope (or pix_automatic.manage in the panel).

Send exactly one of value (fixed amount) or maximumValue (variable amount up to a ceiling). recurrenceId (UUID) identifies the recurrence in this API; recurrenceIdentifier (RR…/RN…) is the Pix scheme id and appears once assigned. Every path that takes {recurrenceId} accepts both.

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Path parameters

accountIdstringRequired
Account identifier.

Headers

X-Tenant-IdstringRequired
Tenant context used for authorization and routing.
Idempotency-KeystringOptional

Optional client-generated idempotency token (recommended for safe retries).

Request

This endpoint expects an object.
frequencyenumRequired
Allowed values:
firstPaymentDatedateRequired
contractobjectRequired
payerobjectRequired
lastPaymentDatedateOptional

Omit for an open-ended recurrence.

valuedoubleOptional
Fixed amount of every charge.
maximumValuedoubleOptional

Ceiling for variable-amount charges.

paymentRetrybooleanOptional
Allows settlement retries after a failed charge.
debtorobjectOptional
Person the charge refers to, when different from the payer.
requestExpirationdatetimeOptional

Deadline for the payer to answer: after today and up to 30 days ahead (Brasília time). Default: 30 days.

Response

Recurrence created, waiting for the payer's authorization
recurrenceIdstringOptionalformat: "uuid"
recurrenceIdentifierstringOptional

RR…/RN…, once assigned.

statusenumOptional
rejectionReasonstringOptional
journeyenumOptional
Allowed values:
frequencyenumOptional
Allowed values:
firstPaymentDatedateOptional
lastPaymentDatedateOptional
valuedoubleOptional
maximumValuedoubleOptional
payerMaximumValuedoubleOptional
Ceiling set by the payer when authorizing.
paymentRetrybooleanOptional
contractobjectOptional
payerobjectOptional
receiverobjectOptional
debtorobjectOptional
qrCodeIdstringOptional
requestedAtdatetimeOptional
requestExpirationdatetimeOptional
authorizedAtdatetimeOptional
createdAtdatetimeOptional
updatedAtdatetimeOptional
historylist of objectsOptional

Errors

400
Bad Request Error
403
Forbidden Error
422
Unprocessable Entity Error
502
Bad Gateway Error