> ## Documentation Index > Fetch the complete documentation index at: https://developers.portao3.com.br/llms.txt > Use this file to discover all available pages before exploring further. # Create a Pix Automatic authorization > Creates a Pix Automático authorization request: the payer gets a link to grant, in their own bank, permission for the wallet to charge their account on a schedule — every month, for example — without approving each charge. 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. ## OpenAPI ````yaml /api-reference/banking.openapi.json post /realms/{realmId}/organizations/{organizationId}/accounts/{accountId}/wallets/{walletId}/pix-billing-automatic openapi: 3.0.3 info: title: Banking version: 1.0.0 description: >- Portão 3 banking API. Every endpoint requires a bearer token in the Authorization header (Authorization: Bearer ) unless its page states otherwise; see the Authentication guide. That requirement is not repeated per endpoint. Generated by tools/openapi from code (routes + security) and the hand-written spec (request/response bodies). Banking attaches a zod validationSchema at the route; request bodies are resolved from it (object + array roots). Responses have no presenter layer, so they stay tier=unknown. Confidence tiers: generated:typed=320 copied:manual=0 unknown=8. servers: - url: https://api.banking.v2.portao3.com.br/ description: production - url: https://api.banking.dev.3pers.com.br/ description: development security: [] tags: - name: Accounts - name: Account Limits - name: Wallets - name: Transaction Limits - name: Transfers - name: Cards - name: Card Limits - name: Cards 3DS - name: Pix Payments - name: Pix Keys - name: PIX Charges - name: PIX Automatic - name: PIX Initiation (Open Finance) - name: PIX Infractions (MED) - name: Boleto Payments - name: Boleto Billing - name: TED Payments - name: Transactions - name: Transaction Reversals - name: Spend Review - name: Cashback - name: Currency Codes paths: /realms/{realmId}/organizations/{organizationId}/accounts/{accountId}/wallets/{walletId}/pix-billing-automatic: post: tags: - PIX Automatic summary: Create a Pix Automatic authorization description: >- Creates a Pix Automático authorization request: the payer gets a link to grant, in their own bank, permission for the wallet to charge their account on a schedule — every month, for example — without approving each charge. operationId: >- postRealmsByRealmIdOrganizationsByOrganizationIdAccountsByAccountIdWalletsByWalletIdPixBillingAutomatic parameters: - name: realmId in: path required: true description: |- ID of your realm. Format: `UUID` schema: type: string format: uuid example: f495ff0c-ab54-4f99-8e92-ca8682e4de9b - name: organizationId in: path required: true description: |- ID of the organization. Format: `UUID` schema: type: string format: uuid example: c4bd3f21-dfbd-44e8-8055-68ba15bed410 - name: accountId in: path required: true description: ID of the organization's account (24 hexadecimal characters). schema: type: string pattern: ^[0-9a-fA-F]{24}$ example: 66f2a1c7b4d3e80012c9a0b4 - name: walletId in: path required: true description: >- ID of the wallet that receives the payments (24 hexadecimal characters), or `default` for the organization's main wallet. schema: type: string pattern: ^([0-9a-fA-F]{24}|default)$ example: 66f2a3d1b4d3e80012c9a0d2 - name: x-environment in: header required: false description: >- Environment of the authorization: `LIVE` (production) or `TEST` (sandbox). When you omit it, `TEST` is used; any other value is rejected. schema: type: string enum: - LIVE - TEST example: LIVE requestBody: required: true content: application/json: schema: type: object properties: description: description: >- 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 type: string pixDict: type: string minLength: 1 description: >- 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. example: financeiro@academiamovimento.com.br debitParty: type: object properties: type: type: string enum: - INDIVIDUAL - BUSINESS description: >- `INDIVIDUAL` for a person (a CPF in `document`) or `BUSINESS` for a company (a CNPJ). example: INDIVIDUAL name: type: string minLength: 1 description: Name of the payer. example: Juliana Ribeiro email: type: string format: email pattern: >- ^(?:[A-Za-z0-9_'+\-]+\.)*[A-Za-z0-9_'+\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$ description: E-mail of the payer. example: juliana.ribeiro@exemplo.com.br document: type: string minLength: 1 description: CPF or CNPJ of the payer, digits only. example: '12345678909' required: - type - name - email - document description: >- The payer: the person or company whose account will be charged. callBackUrlForPaymentProvider: description: >- Pages of your own the payer is sent to when they leave the authorization page. They are not returned in the response. type: object properties: success: description: >- Where the payer is sent after granting the authorization. example: https://www.academiamovimento.com.br/assinatura/sucesso type: string pending: description: >- Where the payer is sent when the authorization is still pending. example: https://www.academiamovimento.com.br/assinatura/pendente type: string error: description: Where the payer is sent when the authorization fails. example: https://www.academiamovimento.com.br/assinatura/erro type: string schedule: type: object properties: minAmount: type: integer minimum: 1 description: >- Smallest amount a recurring charge can have, in cents. Each recurring charge is created with this amount; you can change a recurring charge later, within this range, until it is sent to the payer's bank. example: 18990 maxAmount: type: integer minimum: 1 description: >- Largest amount a recurring charge can have, in cents — the most the payer authorizes per charge. Send the same value as `minAmount` for a fixed amount. example: 18990 type: type: string enum: - WEEKLY - MONTHLY - QUARTERLY - SEMESTER - YEARLY description: >- How often the recurring charges happen: `WEEKLY`, `MONTHLY`, `QUARTERLY` (every 3 months), `SEMESTER` (every 6 months) or `YEARLY`. example: MONTHLY startDate: type: string minLength: 1 description: >- Date of the first recurring charge (`YYYY-MM-DD`), at least two days from today. With `firstPayment`, after `firstPayment.date`. example: '2026-12-10' endDate: type: string minLength: 1 description: >- Last day a recurring charge can fall on (`YYYY-MM-DD`), after `startDate`. The authorization ends the day after it. example: '2027-11-10' dates: description: >- Explicit dates of the recurring charges (`YYYY-MM-DD`), from `startDate` to `endDate`. When you omit it — or send an empty list —, a charge is created on `startDate` and then at every interval of `type` up to `endDate`. --- Example: `["2026-12-10","2027-01-10"]` type: array items: type: string pattern: ^\d{4}-\d{2}-\d{2}$ example: '2026-12-10' required: - minAmount - maxAmount - type - startDate - endDate description: >- The recurrence the payer authorizes and the recurring charges to create. firstPayment: description: >- 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. type: object properties: amount: type: integer minimum: 1 description: Amount of the first payment, in cents. example: 18990 date: type: string minLength: 1 description: >- Date of the first payment (`YYYY-MM-DD`): today or later (Brasília time), and before `schedule.startDate`. example: '2026-11-10' description: description: Description of the first payment. example: Primeira mensalidade type: string required: - amount - date required: - pixDict - debitParty - schedule responses: '201': description: Successful response content: application/json: schema: type: object properties: _id: type: string description: >- ID of the authorization. Use it as `{pixBillingAutomaticId}`. example: 6729f3e1b4d3e80012c9a7c1 environment: type: string enum: - LIVE - TEST description: >- Environment of the authorization: `LIVE` (production) or `TEST` (sandbox). example: LIVE realmId: type: string description: ID of the realm. example: f495ff0c-ab54-4f99-8e92-ca8682e4de9b format: uuid organizationId: type: string description: ID of the organization. example: c4bd3f21-dfbd-44e8-8055-68ba15bed410 format: uuid accountId: type: string description: ID of the organization's account. example: 66f2a1c7b4d3e80012c9a0b4 walletId: type: string description: ID of the wallet that receives the money. example: 66f2a3d1b4d3e80012c9a0d2 pixDict: type: string description: The wallet's Pix key the payments go to. example: financeiro@academiamovimento.com.br status: type: string enum: - CREATED - INITIATED - SCHEDULED - CANCELED - EXPIRED - REVOKED - FAILED description: >- 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. example: CREATED description: type: string description: >- Description of the authorization, shown to the payer. It is also the description of each recurring charge. example: Mensalidade Academia Movimento debitParty: type: object properties: type: type: string enum: - INDIVIDUAL - BUSINESS description: >- `INDIVIDUAL` for a person (a CPF in `document`) or `BUSINESS` for a company (a CNPJ). example: INDIVIDUAL name: type: string description: Name of the payer. example: Juliana Ribeiro email: type: string description: E-mail of the payer. example: juliana.ribeiro@exemplo.com.br document: type: string description: CPF or CNPJ of the payer, digits only. example: '12345678909' required: - type - name - email - document description: The payer. paymentUrl: type: string description: >- 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 paymentLinkValidity: type: string nullable: true description: >- Until when `paymentUrl` can be used — the end of the authorization. `null` when it isn't known. example: '2027-11-11T03:00:00.000Z' format: date-time schedule: type: object properties: type: type: string enum: - WEEKLY - MONTHLY - QUARTERLY - SEMESTER - YEARLY description: >- How often the recurring charges happen: `WEEKLY`, `MONTHLY`, `QUARTERLY` (every 3 months), `SEMESTER` (every 6 months) or `YEARLY`. example: MONTHLY minAmount: type: number description: >- Smallest amount a recurring charge can have, in cents. Each recurring charge is created with this amount. example: 18990 maxAmount: type: number description: >- Largest amount a recurring charge can have, in cents — the most the payer authorizes per charge. example: 18990 startDate: type: string description: >- When the authorization starts: two days before the `schedule.startDate` you sent — or the day after the first payment, when that is later. Midnight UTC of that day. example: '2026-12-08T00:00:00.000Z' format: date-time endDate: type: string description: >- When the authorization ends: the day after the `schedule.endDate` you sent, at midnight UTC. No charge can be made after it. example: '2027-11-11T00:00:00.000Z' format: date-time required: - type - minAmount - maxAmount - startDate - endDate description: The recurrence the payer authorizes. firstPayment: type: object properties: _id: type: string description: ID of the first payment's record. example: 6729f3e1b4d3e80012c9a7c2 amount: type: number description: Amount of the first payment, in cents. example: 18990 date: type: string description: Day of the first payment, at midnight UTC. example: '2026-11-10T00:00:00.000Z' format: date-time description: type: string description: Description of the first payment, when you sent one. example: Primeira mensalidade required: - _id - amount - date description: The first payment, when you asked for one. external: type: object properties: customerId: type: string description: The institution's ID of the payer. example: 0b7e0c52-5a8e-4d4a-9a61-2f3c4d5e6f70 recipientId: type: string description: >- The institution's ID of the receiving account — your wallet. example: 1c8f1d63-6b9f-4e5b-8b72-3a4d5e6f7081 requestId: type: string description: >- The institution's ID of the request. It is also the last part of `paymentUrl`. example: 2d902e74-7ca0-4f6c-9c83-4b5e6f708192 description: References at the payment institution. createdAt: type: string description: When the authorization was created. example: '2026-11-05T14:20:31.402Z' format: date-time updatedAt: type: string description: When the authorization last changed. example: '2026-11-05T14:31:07.118Z' format: date-time __v: type: number description: Internal revision counter of the record. example: 0 schedules: type: array items: type: object properties: _id: type: string description: >- ID of the charge. Use it as `{pixBillingAutomaticScheduleId}`. example: 6729f3e1b4d3e80012c9a7d4 environment: type: string enum: - LIVE - TEST description: >- Environment of the charge: `LIVE` (production) or `TEST` (sandbox). example: LIVE realmId: type: string description: ID of the realm. example: f495ff0c-ab54-4f99-8e92-ca8682e4de9b format: uuid organizationId: type: string description: ID of the organization. example: c4bd3f21-dfbd-44e8-8055-68ba15bed410 format: uuid accountId: type: string description: ID of the organization's account. example: 66f2a1c7b4d3e80012c9a0b4 walletId: type: string description: ID of the wallet that receives the money. example: 66f2a3d1b4d3e80012c9a0d2 pixBillingAutomaticId: type: string description: ID of the authorization this charge belongs to. example: 6729f3e1b4d3e80012c9a7c1 amount: type: number description: Amount of the charge, in cents. example: 18990 status: type: string enum: - CREATED - SCHEDULED - CANCELED - EXPIRED - FAILED - SCHEDULE_ERROR - PAID - RETRY description: >- Where the charge stands: - `CREATED` — waiting. A recurring charge is sent to the payer's bank between 2 and 10 days before `scheduledTo`, once the payer has granted the authorization; until then you can change its amount. The first payment goes with the authorization itself and is charged when the payer grants it. A recurring charge still `CREATED` after its date: without `external.scheduleId`, the payer's bank most likely refused it when it was sent (its history has a `SCHEDULE_ATTEMPT_FAILED` event) — in rare cases the bank accepted it and the confirmation was lost, so confirm with support before charging it another way; with one, the bank is still processing it — wait for the outcome. - `SCHEDULED` — sent to the payer's bank, which debits it on `scheduledTo`. - `PAID` — paid; the money is in the wallet. - `FAILED` — the payer's bank couldn't debit it and it won't be tried again: a final refusal (for example, the payer's limit for the period was reached) or the new attempts ran out. `error` says why. - `SCHEDULE_ERROR` — it couldn't be sent to the payer's bank and won't be. `error` says why; treat it like `FAILED`. - `CANCELED` — canceled, by you or because the authorization was canceled or revoked. - `EXPIRED` — the payer never granted the authorization. - `RETRY` — not used today. example: CREATED description: type: string description: Description of the charge. example: Mensalidade Academia Movimento isFirstPayment: type: boolean description: >- `true` for the first payment, absent for a recurring charge. example: true scheduledTo: type: string description: >- Day the charge is debited, at midnight UTC: its due date, or the date of the latest new attempt after a failure. example: '2026-12-10T00:00:00.000Z' format: date-time attempts: type: array items: type: object properties: _id: type: string description: ID of the attempt's record. example: 672c1f00b4d3e80012c9a9f1 attempt: type: number description: >- Number of the attempt: `1` for the one on the due date, then one more for each new attempt. example: 1 date: type: string description: Day of the attempt, at midnight UTC. example: '2026-12-10T00:00:00.000Z' format: date-time required: - _id - attempt - date description: >- One attempt to debit a charge: the first, on its due date, and each new one asked for after the payer's bank failed to debit it. description: >- The attempts to debit the charge, oldest first: the first, on `scheduledTo`, then each new attempt asked for after the payer's bank failed to debit it. external: type: object properties: scheduleId: type: string description: >- The institution's ID of the charge. Set once the charge is sent to the payer's bank. example: 3ea13f85-8db1-4a7d-8d94-5c6f708192a3 endToEndId: type: string description: >- End-to-end ID of the Pix that debits the charge, once the payment institution reports it. example: E00000000202612101203a1b2c3d4e5f scheduleAttemptsCount: type: number description: >- How many times the charge was sent to the payer's bank: `1`, plus one for each time it was sent again after a failure before the due date. example: 1 description: >- References at the payment institution, once the charge is sent to the payer's bank. error: type: object properties: code: type: string description: >- Code of the failure: a code of the Pix Automático rules — for example `LIMITE_PERIODO_VALOR_EXCEDIDO` (the payer's limit for the period was reached), `CONSENTIMENTO_REVOGADO` (the payer revoked the authorization) or `FORA_PRAZO_PERMITIDO` (outside the allowed window) —, `UNKNOWN_ERROR` when no reason was given, or the HTTP status of a request to the payment institution that failed (`400`, `500`). example: LIMITE_PERIODO_VALOR_EXCEDIDO description: type: string description: Description of the failure. example: Limite de valor do período excedido detail: type: string description: More detail on the failure, when there is any. example: O valor do pagamento excede o limite do período title: type: string description: Title of the failure, when there is one. example: Payment failed description: Why the charge failed, when it did. createdAt: type: string description: When the charge was created. example: '2026-11-05T14:20:31.655Z' format: date-time updatedAt: type: string description: When the charge last changed. example: '2026-12-03T03:30:12.904Z' format: date-time __v: type: number description: Internal revision counter of the record. example: 0 required: - _id - environment - realmId - organizationId - accountId - walletId - pixBillingAutomaticId - amount - status - scheduledTo - attempts - createdAt - updatedAt description: >- One charge of an authorization: the first payment or a recurring charge. description: >- Every charge of the authorization: the first payment and each recurring charge. required: - _id - accountId - createdAt - debitParty - environment - external - organizationId - paymentUrl - pixDict - realmId - schedule - schedules - status - updatedAt - walletId description: An authorization with all its charges. '404': description: >- `ACCOUNT_NOT_FOUND` — No account with this ID exists in the organization. `WALLET_NOT_FOUND` — The account has no wallet with this ID in this environment — or, with `walletId` `default`, no main wallet. `PIX_DICT_NOT_FOUND` — The wallet has no active Pix key with the value in `pixDict`, in this environment. content: application/json: schema: type: object properties: traceId: type: string description: >- Identifier of the request that failed. Quote it when contacting support. example: 1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b code: type: string enum: - ACCOUNT_NOT_FOUND - WALLET_NOT_FOUND - PIX_DICT_NOT_FOUND description: >- Stable, machine-readable error code. Branch on this, never on `message`. origin: type: string enum: - BANKING description: Service that produced the error. message: type: string description: >- Human-readable explanation. Its wording may change without notice. required: - traceId - code - origin - message example: traceId: 1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b code: ACCOUNT_NOT_FOUND origin: BANKING message: Account not found '422': description: >- `BAD_REQUEST` — A path or body field is invalid — for example a `schedule.startDate` less than two days from today, or a `firstPayment.date` that isn't before it; `fields` lists each one. content: application/json: schema: type: object properties: traceId: type: string description: >- Identifier of the request that failed. Quote it when contacting support. example: 1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b code: type: string enum: - BAD_REQUEST description: >- Stable, machine-readable error code. Branch on this, never on `message`. origin: type: string enum: - BANKING description: Service that produced the error. message: type: string description: >- Human-readable explanation. Its wording may change without notice. fields: type: array description: >- One entry per invalid request field (validation errors only). items: type: object properties: field: type: string description: >- Path of the invalid field, e.g. `label` or `values[0].value`. example: label message: type: string description: Why the field was rejected. example: label is required code: type: string description: >- `_` — e.g. `LABEL_REQUIRED`, `TYPE_ONE_OF`, `VALUES_VALUE_TYPE_ERROR`. example: LABEL_REQUIRED values: type: array items: type: string description: >- The accepted values, when the field is an enumeration. required: - field - message - code required: - traceId - code - origin - message example: traceId: 1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b code: BAD_REQUEST origin: BANKING message: >- Bad Request: Your request is invalid or incomplete. Please make sure you are requesting with the right fields. fields: - field: pixDict message: 'Invalid input: expected string, received undefined' code: PIXDICT_REQUIRED '500': description: >- `INTERNAL_SERVER_ERROR` — An unexpected failure — for example, the payment institution didn't answer. If it persists, contact support with the `traceId`. content: application/json: schema: type: object properties: traceId: type: string description: >- Identifier of the request that failed. Quote it when contacting support. example: 1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b code: type: string enum: - INTERNAL_SERVER_ERROR description: >- Stable, machine-readable error code. Branch on this, never on `message`. origin: type: string enum: - BANKING description: Service that produced the error. message: type: string description: >- Human-readable explanation. Its wording may change without notice. required: - traceId - code - origin - message example: traceId: 1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b code: INTERNAL_SERVER_ERROR origin: BANKING message: Internal Server error ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.