Pix Automático Subscriptions

With Pix Automático, the payer authorizes the recurring debit once, in their bank app, by scanning a QR code. From then on, the payer’s bank debits each cycle and Pagou tells you the outcome through subscription webhooks.

How it works

Create the customer with POST /v2/customers, including a CPF or CNPJ.
Create the subscription with payment_method: "pix_automatic". No card token is involved.
Show authorization.qr_code to the payer.
The payer authorizes the recurring debit in their bank app.
The payer’s bank debits each cycle. Listen to subscription webhooks to follow authorizations, payments, failures, and cancellation.

What changes compared to card subscriptions:

	Card	Pix Automático
Status right after creation	`active` or `trialing`	`incomplete`, until the payer authorizes
Who starts each charge	Pagou	the payer’s bank
Cancellation	at the end of the period (`cancel_scheduled`), emits `subscription.updated`	immediate, emits `subscription.canceled`
Plan change	available	not available

Prerequisites

Subscriptions must be enabled for your account (403 otherwise), and so must Pix Automático (422 otherwise). See Errors.
The customer must exist in /v2/customers with a CPF or CNPJ in document. Address and phone are optional.
currency must be BRL.

Create a subscription without a trial

Without trial_end, the same QR code authorizes the recurring debit and pays the first cycle.

curl --request POST \
  --url https://api.pagou.ai/v2/subscriptions \
  --header "Authorization: Bearer YOUR_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "customer_id": "9f9a8df6-0b3d-40d5-9f6b-a9e96c0a9101",
    "payment_method": "pix_automatic",
    "amount": 4900,
    "currency": "BRL",
    "interval": "month",
    "interval_count": 1,
    "billing_day_of_month": 10,
    "comment": "Pro plan",
    "failure_policy": "retry_then_cancel",
    "metadata": {
      "plan": "pro"
    }
  }'

Response 201:

{
  "success": true,
  "requestId": "0190a2b4-18a7-7de0-9a43-69b7cf261201",
  "data": {
    "id": "019e5d23-6ec8-73de-9c95-06093c62ba00",
    "customerId": "9f9a8df6-0b3d-40d5-9f6b-a9e96c0a9101",
    "status": "incomplete",
    "paymentMethod": "pix_automatic",
    "billingModel": "provider_initiated",
    "billingDayOfMonth": 10,
    "interval": "month",
    "intervalCount": 1,
    "amount": 4900,
    "currency": "BRL",
    "trialEnd": null,
    "currentPeriodStart": "2026-09-23T14:00:00.000Z",
    "currentPeriodEnd": "2026-10-23T14:00:00.000Z",
    "cancelAtPeriodEnd": false,
    "canceledAt": null,
    "failurePolicy": "retry_then_cancel",
    "retryOffsetsDays": [1, 2, 3, 4, 5],
    "cancellationReason": null,
    "customerEmail": "buyer@example.com",
    "cardLast4": null,
    "metadata": { "plan": "pro" },
    "informations": null,
    "products": [],
    "authorization": {
      "type": "pix_qr",
      "qr_code": "00020101021226870014br.gov.bcb.pix2565qr.example.com/rec/019e5d236ec85204000053039865802BR6304A1B2",
      "expires_at": "2026-09-24T14:00:00.000Z",
      "status": "awaiting_customer"
    },
    "recurringAuthorization": {
      "status": "pending"
    },
    "createdAt": "2026-09-23T14:00:00.000Z",
    "updatedAt": "2026-09-23T14:00:00.000Z"
  }
}

The subscription stays incomplete until the payer authorizes and the first debit is paid. At that point it becomes active and you receive subscription.started with previous_status: "incomplete". This flow does not send subscription.created.

Create a subscription with a trial

Send trial_end (ISO 8601, in the future) and the QR code only authorizes the recurring debit. Nothing is charged until the trial ends. Trials depend on your account configuration. When they are not available, the request returns 422 with PIX_AUTOMATIC_TRIAL_NOT_SUPPORTED and nothing is created. Where trials are available, also send billing_day_of_month. The first debit is scheduled for the first occurrence of that day on or after the signup date, and that date must fall on or after trial_end and at least 3 full days (72 hours) after the moment of signup. Without billing_day_of_month, the billing day is the signup day, so the first debit would fall before the trial ends and the request is rejected. When the dates do not fit, the request returns 422 with PIX_AUTHORIZATION_FAILED and a detail that explains why. In this example the subscription is created on September 23, with trial_end on October 7 and billing_day_of_month: 10, so the first debit is scheduled for October 10:

curl --request POST \
  --url https://api.pagou.ai/v2/subscriptions \
  --header "Authorization: Bearer YOUR_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "customer_id": "9f9a8df6-0b3d-40d5-9f6b-a9e96c0a9101",
    "payment_method": "pix_automatic",
    "amount": 4900,
    "currency": "BRL",
    "interval": "month",
    "interval_count": 1,
    "billing_day_of_month": 10,
    "trial_end": "2026-10-07T00:00:00.000Z"
  }'

Response 201:

{
  "success": true,
  "requestId": "0190a2b4-18a7-7de0-9a43-69b7cf261202",
  "data": {
    "id": "019e5d23-7a10-7c4e-8f21-3b5d8e0a1c02",
    "customerId": "9f9a8df6-0b3d-40d5-9f6b-a9e96c0a9101",
    "status": "incomplete",
    "paymentMethod": "pix_automatic",
    "billingModel": "provider_initiated",
    "billingDayOfMonth": 10,
    "interval": "month",
    "intervalCount": 1,
    "amount": 4900,
    "currency": "BRL",
    "trialEnd": "2026-10-07T00:00:00.000Z",
    "currentPeriodStart": "2026-09-23T14:00:00.000Z",
    "currentPeriodEnd": "2026-10-07T00:00:00.000Z",
    "cancelAtPeriodEnd": false,
    "canceledAt": null,
    "failurePolicy": "retry_then_cancel",
    "retryOffsetsDays": [1, 2, 3, 4, 5],
    "cancellationReason": null,
    "customerEmail": "buyer@example.com",
    "cardLast4": null,
    "metadata": null,
    "informations": null,
    "products": [],
    "authorization": {
      "type": "pix_qr",
      "qr_code": "00020101021226870014br.gov.bcb.pix2565qr.example.com/rec/019e5d237a107c4e5204000053039865802BR6304C3D4",
      "expires_at": null,
      "status": "awaiting_customer"
    },
    "recurringAuthorization": {
      "status": "pending"
    },
    "createdAt": "2026-09-23T14:00:00.000Z",
    "updatedAt": "2026-09-23T14:00:00.000Z"
  }
}

When the payer approves the authorization, the subscription becomes trialing and you receive subscription.created (with latest_transaction: null). Three days before trial_end you receive subscription.trial_will_end, if the subscription is already trialing by then. The first debit after the trial makes it active and sends subscription.started.

Request fields

Field	Required	Notes
`customer_id`	yes	public customer id. The customer needs a CPF or CNPJ.
`payment_method`	yes	`"pix_automatic"`. Do not send `token`: the request is rejected.
`amount`	yes	cents, billed every cycle. Some accounts require at least `100` (R$ 1,00).
`interval` / `interval_count`	yes / no	see Billing intervals. `interval_count` defaults to `1`.
`billing_day_of_month`	no	`1` to `31`. Values above `27` are treated as `27`. Without a trial it is a preference, not a guaranteed debit date. With a trial, send it: it schedules the first debit (see Create a subscription with a trial).
`comment`	no	up to 140 characters. It may be shown to the payer, depending on your account configuration.
`trial_end`	no	see Create a subscription with a trial.
`failure_policy`	no	`retry_then_cancel` (default) or `immediate_cancel`. See Failed debits.
`metadata`, `informations`, `idempotency_key`	no	same behavior as card subscriptions.

Billing intervals

`interval`	`interval_count`	Availability
`week`	`1`	available
`month`	`1`, `6`, `12`	available
`month`	`3`	depends on your account configuration
`day`	any	never available

Any other combination, or one your account does not support, returns 422 with PIX_AUTHORIZATION_FAILED and a detail that says the interval is not supported.

Show the QR code

The authorization block is what the payer needs:

Field	Meaning
`type`	always `pix_qr`
`qr_code`	Pix copy-and-paste code. Render it as a QR code or offer it for copying.
`payment_link_url`	hosted page where the payer can authorize, when available. It may be absent.
`expires_at`	when the code expires, when known. It may be `null`.
`status`	`awaiting_customer`

GET /v2/subscriptions/{id} returns authorization only while the authorization is pending. After the payer approves or rejects it, the block disappears. If the payer never authorizes, what happens depends on your account configuration: the subscription either stays incomplete, or is canceled when the code expires and you receive subscription.canceled. To stop waiting, cancel it yourself (see Cancel). recurringAuthorization.status tells you where the authorization stands: pending, approved, rejected, cancel_pending, or canceled. On GET by id, recurringAuthorization.lastDebit shows the most recent debit attempt.

What to store

subscription id
customer id
current status
authorization.qr_code, while the authorization is pending
recurringAuthorization.status
latest_transaction.id from the webhooks, when present

Status and webhooks

Moment	Status	Webhook (`data.event_type`)
subscription created, without a trial	`incomplete`	none
payer authorized and first debit paid, without a trial	`active`	`subscription.started`
subscription created, with a trial	`incomplete`	none
payer authorized, with a trial	`trialing`	`subscription.created`
3 days before `trial_end`, if already `trialing`	`trialing`	`subscription.trial_will_end`
first debit paid after the trial	`active`	`subscription.started`
payer rejected the authorization, or let it expire (depending on your account configuration)	`canceled`	`subscription.canceled`, with `failure_reason`
a later cycle was paid	`active`	`subscription.renewed`
a debit failed	see Failed debits	`subscription.payment_failed`
subscription canceled	`canceled`	`subscription.canceled`

Things to know when you handle these events:

Pix Automático charges are reported only through subscription.* events. You do not receive transaction.* webhooks for them.
latest_transaction.method is "pix". The payload does not say which payment method the subscription uses, so identify Pix Automático subscriptions by the id you stored, or read paymentMethod with GET /v2/subscriptions/{id}.
failure_reason is informative. Do not build logic on specific values.

Failed debits

The payer’s bank may try a debit more than once. Those intermediate attempts do not generate events. When no attempts are left, you receive subscription.payment_failed with attempt_number and failure_reason.

If it was the first debit of a subscription without a trial, the subscription stays incomplete.
Otherwise (the first debit after a trial, or a later cycle), with failure_policy: retry_then_cancel the subscription becomes past_due and you receive subscription.past_due. For a later cycle, a debit paid afterwards makes it active again and sends subscription.renewed.
A failed debit does not create a new transaction. On subscription.payment_failed and subscription.past_due, latest_transaction is the most recent transaction of the subscription, which is usually the previous paid cycle.
retry_offsets_days is accepted but has no effect: retry timing follows the Pix Automático rules and cannot be configured.
Anything else failure_policy does for Pix Automático depends on your account configuration. subscription.canceled is the only confirmation that a subscription ended.

Cancel

POST /v2/subscriptions/{id}/cancel works while the subscription is incomplete, trialing, active, or past_due. For Pix Automático the cancellation is immediate: it is never scheduled for the end of the period, the status never becomes cancel_scheduled, and the webhook is subscription.canceled, not subscription.updated. The response comes in one of two forms, depending on your account configuration:

Already canceled: status is canceled and recurringAuthorization.status is canceled.
Waiting for confirmation: status keeps its current value and recurringAuthorization.status is cancel_pending. The subscription becomes canceled once the cancellation is confirmed, and you receive subscription.canceled then.

In both cases, treat subscription.canceled as the source of truth. Repeating the call on a subscription that is canceled, or whose cancellation is waiting for confirmation, returns 200 with no change. Two concurrent calls on the same subscription may return 409 with SUBSCRIPTION_CANCEL_IN_PROGRESS; retry after a short wait.

Limitations

Plan changes are not available. PATCH /v2/subscriptions/{id} with product_id returns 422 and the plan stays the same: PLAN_CHANGE_UNAVAILABLE_FOR_PAYMENT_METHOD when the subscription is tied to a catalog plan, or SUBSCRIPTION_HAS_NO_CATALOG_PLAN / PRODUCT_NOT_FOUND when it is not. To move the payer to another plan, cancel the subscription and create a new one, which needs a new authorization.
Billing intervals are limited to the table in Request fields.
Trials depend on your account configuration.
Retry spacing cannot be configured: retry_offsets_days is ignored.
The debit date is not guaranteed. Follow the webhooks instead of expecting a charge on a fixed day.

Errors

Situation	HTTP	`code`
Subscriptions are not enabled for your account	`403`	`FORBIDDEN`
Pix Automático is not enabled for your account	`422`	`UNSUPPORTED_PAYMENT_METHOD`, `PIX_AUTOMATIC_ACCOUNT_NOT_ELIGIBLE`, or `PIX_AUTOMATIC_SUBACCOUNT_REQUIRED`
Pix Automático is not configured for your account	`400`	`BAD_REQUEST`
The customer has no CPF or CNPJ	`400`	`BAD_REQUEST`
Unknown `customer_id`	`404`	`NOT_FOUND`
`trial_end` is not available for your account	`422`	`PIX_AUTOMATIC_TRIAL_NOT_SUPPORTED`
Unsupported interval, amount below your account’s minimum, or trial dates that do not fit `billing_day_of_month`	`422`	`PIX_AUTHORIZATION_FAILED`
The authorization could not be set up. The subscription is created as `canceled`.	`422`	`PIX_AUTHORIZATION_FAILED`
Plan change requested	`422`	`PLAN_CHANGE_UNAVAILABLE_FOR_PAYMENT_METHOD`, or `SUBSCRIPTION_HAS_NO_CATALOG_PLAN` / `PRODUCT_NOT_FOUND` when the subscription is not tied to a catalog plan
Cancellation already running for the same subscription	`409`	`SUBSCRIPTION_CANCEL_IN_PROGRESS`

When Pix Automático is not enabled or not configured, contact support to enable it for your account.

Sandbox

In the sandbox (https://api.sandbox.pagou.ai) there is no payer’s bank on the other side: nobody scans the QR code and nothing is debited on its own. You play the payer’s bank with POST /v2/subscriptions/{id}/simulate. The subscription moves exactly as it would in production and you receive the same webhooks. Create the customer and the subscription as described above, with your sandbox token. Then send one event per call:

curl --request POST \
  --url https://api.sandbox.pagou.ai/v2/subscriptions/019e5d23-6ec8-73de-9c95-06093c62ba00/simulate \
  --header "Authorization: Bearer YOUR_SANDBOX_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{ "event": "authorize" }'

The response is 200 with the updated subscription, in the same shape as GET /v2/subscriptions/{id}.

`event`	Accepted while `recurringAuthorization.status` is	Without a trial	With a trial
`authorize`	`pending`	the payer authorizes and the first cycle is paid: `active`, `subscription.started`	the payer authorizes: `trialing`, `subscription.created`
`reject`	`pending`	the payer refuses: `canceled`, `subscription.canceled` with `failure_reason`	same
`pay`	`approved`	the next cycle is paid: `subscription.renewed`	the first debit is paid: `active`, `subscription.started`; after that, `subscription.renewed`
`fail`	`approved`	the debit fails: `subscription.payment_failed`, then see below	same

After fail, with failure_policy: retry_then_cancel the subscription becomes past_due and you receive subscription.past_due; for a later cycle, a pay makes it active again with subscription.renewed. With immediate_cancel it becomes canceled and you receive subscription.canceled. With a trial, a fail before the first debit is paid leaves the subscription past_due and no pay recovers it: cancel it and create a new one to keep testing. What to know about the sandbox:

One call is one event. Each pay pays one cycle right away, whatever the billing interval.
The subscription moves only when you call the endpoint. Do not rely on time-based events such as subscription.trial_will_end in the sandbox.
An event that does not fit the current authorization or status returns 409 with SUBSCRIPTION_SIMULATION_NOT_APPLICABLE and changes nothing: for example, pay before authorize, or authorize twice.
authorization.qr_code has the Pix format, but it does not set up a real recurring authorization: do not scan it with a bank app, use authorize instead. expires_at is null and the authorization never expires on its own: use reject to test a refused authorization.
The sandbox accepts trial_end without checking it against billing_day_of_month, and the first debit happens when you send pay. In production, trials depend on your account configuration and the dates must fit (see Create a subscription with a trial).
Billing intervals are week × 1 and month × 1, 6, or 12. month × 3 is refused, and so is an amount below 100.
A cancellation responds already canceled.
Do not use PUT /v2/transactions/{id} on a Pix Automático charge: it changes the transaction but not the subscription.
The Pix values in Test Data (documents and the 7300 amount) do not apply to Pix Automático.
The route exists only in the sandbox. In production it returns 404.

Recurring Billing

How it works

Prerequisites

Create a subscription without a trial

Create a subscription with a trial

Request fields

Billing intervals

Show the QR code

What to store

Status and webhooks

Failed debits

Cancel

Limitations

Errors

Sandbox

Read next

​How it works

​Prerequisites

​Create a subscription without a trial

​Create a subscription with a trial

​Request fields

​Billing intervals

​Show the QR code

​What to store

​Status and webhooks

​Failed debits

​Cancel

​Limitations

​Errors

​Sandbox

​Read next

How it works

Prerequisites

Create a subscription without a trial

Create a subscription with a trial

Request fields

Billing intervals

Show the QR code

What to store

Status and webhooks

Failed debits

Cancel

Limitations

Errors

Sandbox

Read next