Skip to main content
POST
Create a Pix Automatic authorization
  1. Create it with the payer (debitParty), the wallet’s Pix key that receives the payments (pixDict), the recurrence (schedule) and, optionally, a first payment. The answer is the authorization, status CREATED, with every charge in schedules (status CREATED) and the paymentUrl to send to the payer.
  2. The payer opens paymentUrl and grants the authorization in their bank: status moves to INITIATED and then SCHEDULED. The first payment, if any, is charged on its date.
  3. Each recurring charge is sent to the payer’s bank 2 to 10 days before its date and debited on it: its status moves to SCHEDULED and then PAID — or FAILED, with the reason in error. A charge the payer’s bank refused to schedule ends as SCHEDULE_ERROR, or stays CREATED past its date with no external.scheduleId and a SCHEDULE_ATTEMPT_FAILED event in the history — usually a refusal; in rare cases the bank accepted it and the confirmation was lost, so confirm with support before charging it another way. One CREATED past its date WITH external.scheduleId is still being processed by the bank. Follow them with GET .../pix-billing-automatic/{pixBillingAutomaticId}.
The recurring charges fall on schedule.dates, or — when you omit it or send an empty list — on schedule.startDate and then at every interval of schedule.type up to schedule.endDate. Each is created with schedule.minAmount; until it is sent to the payer’s bank you can change it, within schedule.minAmount and schedule.maxAmount, with PUT .../schedules/{pixBillingAutomaticScheduleId}. The first payment can’t change, nor be canceled on its own while it is still CREATED: it goes with the authorization itself. The answer keeps the dates of the authorization, not the ones you sent: schedule.startDate is two days before the schedule.startDate you sent (or the day after the first payment, when that is later) and schedule.endDate the day after the schedule.endDate you sent. If the payer doesn’t grant the authorization before the first charges are due, it expires (EXPIRED). The payer can revoke it in their bank at any time (REVOKED); to stop it yourself, use POST .../pix-billing-automatic/{pixBillingAutomaticId}/cancel. When the payment institution refuses the request, nothing is created and the answer carries the institution’s HTTP status, error code and message. Use default as walletId for the organization’s main wallet. Any member of the organization can create one.

Headers

​
x-environment
enum<string>

Environment of the authorization: LIVE (production) or TEST (sandbox). When you omit it, TEST is used; any other value is rejected.

Available options:
LIVE,
TEST

Path Parameters

​
realmId
string<uuid>
required

ID of your realm.

Format: UUID

​
organizationId
string<uuid>
required

ID of the organization.

Format: UUID

​
accountId
string
required

ID of the organization's account (24 hexadecimal characters).

Pattern: ^[0-9a-fA-F]{24}$
​
walletId
string
required

ID of the wallet that receives the payments (24 hexadecimal characters), or default for the organization's main wallet.

Pattern: ^([0-9a-fA-F]{24}|default)$

Body

application/json
​
pixDict
string
required

One of the wallet's active Pix keys, as registered (an e-mail, a phone number, a CPF or CNPJ, or a random key). The payments go to it.

Minimum string length: 1
Example:

"financeiro@academiamovimento.com.br"

​
debitParty
object
required

The payer: the person or company whose account will be charged.

​
schedule
object
required

The recurrence the payer authorizes and the recurring charges to create.

​
description
string

Description of the authorization, shown to the payer — for example the plan's name. It is also the description of each recurring charge.

Example:

"Mensalidade Academia Movimento"

​
callBackUrlForPaymentProvider
object

Pages of your own the payer is sent to when they leave the authorization page. They are not returned in the response.

​
firstPayment
object

A first payment, charged on its date once the payer grants the authorization, apart from the recurring charges — for example a sign-up fee or the first month.

Response

Successful response

An authorization with all its charges.

​
_id
string
required

ID of the authorization. Use it as {pixBillingAutomaticId}.

Example:

"6729f3e1b4d3e80012c9a7c1"

​
environment
enum<string>
required

Environment of the authorization: LIVE (production) or TEST (sandbox).

Available options:
LIVE,
TEST
Example:

"LIVE"

​
realmId
string<uuid>
required

ID of the realm.

Example:

"f495ff0c-ab54-4f99-8e92-ca8682e4de9b"

​
organizationId
string<uuid>
required

ID of the organization.

Example:

"c4bd3f21-dfbd-44e8-8055-68ba15bed410"

​
accountId
string
required

ID of the organization's account.

Example:

"66f2a1c7b4d3e80012c9a0b4"

​
walletId
string
required

ID of the wallet that receives the money.

Example:

"66f2a3d1b4d3e80012c9a0d2"

​
pixDict
string
required

The wallet's Pix key the payments go to.

Example:

"financeiro@academiamovimento.com.br"

​
status
enum<string>
required

Where the authorization stands:

  • CREATED — waiting for the payer to open paymentUrl and grant it in their bank.
  • INITIATED — the payer started the authorization.
  • SCHEDULED — the payer granted it; the charges follow schedules. It stays SCHEDULED after the last charge.
  • CANCELED — you canceled it.
  • REVOKED — the payer revoked it in their bank; the pending charges were canceled.
  • EXPIRED — the payer didn't grant it before the first charges were due.
  • FAILED — not used today.
Available options:
CREATED,
INITIATED,
SCHEDULED,
CANCELED,
EXPIRED,
REVOKED,
FAILED
Example:

"CREATED"

​
debitParty
object
required

The payer.

​
paymentUrl
string
required

Link where the payer reviews the authorization and grants it in their bank. Send it to the payer.

Example:

"https://pay.portao3.com.br/2d902e74-7ca0-4f6c-9c83-4b5e6f708192"

​
schedule
object
required

The recurrence the payer authorizes.

​
external
object
required

References at the payment institution.

​
createdAt
string<date-time>
required

When the authorization was created.

Example:

"2026-11-05T14:20:31.402Z"

​
updatedAt
string<date-time>
required

When the authorization last changed.

Example:

"2026-11-05T14:31:07.118Z"

​
schedules
object[]
required

Every charge of the authorization: the first payment and each recurring charge.

​
description
string

Description of the authorization, shown to the payer. It is also the description of each recurring charge.

Example:

"Mensalidade Academia Movimento"

​
paymentLinkValidity
string<date-time> | null

Until when paymentUrl can be used — the end of the authorization. null when it isn't known.

Example:

"2027-11-11T03:00:00.000Z"

​
firstPayment
object

The first payment, when you asked for one.

​
__v
number

Internal revision counter of the record.

Example:

0