Notifications

Everything that happens to a recurrence and its charges is sent by POST to the URL in the recurrence's webhook field, set on creation or with a PATCH.

You receive two kinds of notification:

Kind	What it announces	Format
Deposit callback	The money came in: a charge settled, or the activation payment	The same as any Pix: `"type": "transaction"`
Lifecycle events	State changes of the recurrence and its charges	`"type": "automatic_pix"`, with `resource` and `event`

Tell them apart by the type field.

⚠️

Without a webhook on the recurrence, you receive neither. Set the URL when you create the recurrence, or later with PATCH.

Endpoint requirements

The same as the other webhooks:

✅ Accept POST with a JSON body
✅ Respond 2xx within 5 seconds. Do heavy processing afterwards.
✅ Respond directly, without redirecting: a 3xx counts as a failed delivery
✅ Be idempotent: the same notification may arrive more than once

A failed delivery is retried later. The events of one recurrence arrive in the order they happened.

How payment arrives

Every Automatic Pix payment, each cycle charge that settles and also the journey 3 activation payment, arrives as the standard PixToPay deposit callback: the same format as an ordinary Pix, described in Webhooks. If you already integrate Pix with PixToPay, there is nothing new to build here. The payment shows up in your reports and your balance like any other deposit.

Paid deposit (status 1)

{
  "id": 987654321,
  "transaction_id": "assinatura-8891-2026-11-01",
  "currency": "BRL",
  "amount": 99.9,
  "type": "transaction",
  "method": "pix",
  "status": 1,
  "created_at": "2026-10-27T06:00:00.000Z",
  "paid_at": "2026-11-03T09:12:40.000Z",
  "name": "Maria Silva",
  "document_number": "12345678909",
  "phone_number": null,
  "email": "maria.silva@exemplo.com.br",
  "payer": { "name": "Maria Silva", "document_number": "12345678909" },
  "e2eId": "E6070119020261103104500a1b2c3d4"
}

Lifecycle events

State changes of the recurrence and its charges are sent as events. They all have "type": "automatic_pix", the resource in resource (recurrence or charge) and what happened in event.

Event	Sent when
`recurrence.created`	The recurrence was created (`POST /recurrences`).
`recurrence.approved`	The payer authorized. From here on PixToPay creates the cycles' charges.
`recurrence.rejected`	The payer or their bank refused the authorization.
`recurrence.expired`	The authorization deadline passed with no answer.
`recurrence.cancelled`	The recurrence was cancelled: by you (`PATCH`), by the payer in their banking app, or by the bank.
`charge.created`	PixToPay created the cycle's charge, `charge_lead_days` days before the due date (default 5).
`charge.scheduled`	The payer's bank scheduled the debit (the charge is `ACTIVE`).
`charge.cancelled`	The charge was cancelled: by you (`PATCH /charges/:charge_id`) or by the payer's bank.
`charge.expired`	A debit attempt failed, typically because of insufficient funds. The charge stays `ACTIVE`; without this event you would not know the debit failed.
`charge.retry_scheduled`	A retry was scheduled.

A settled charge already arrives as the paid deposit.

Recurrence event body

resource: "recurrence". Example of recurrence.approved:

{
  "id": 42,
  "transaction_id": "assinatura-8891",
  "amount": 99.9,
  "status": "APPROVED",
  "created_at": "2026-09-22T13:00:00.000Z",
  "type": "automatic_pix",
  "resource": "recurrence",
  "event": "approved",
  "method": "pix",
  "currency": "BRL",
  "external_id": "RR9012345620260922f3a1c7b28e4",
  "name": "Maria Silva",
  "document_number": "12345678909",
  "recurrence": {
    "recurrence_id": "RR9012345620260922f3a1c7b28e4",
    "status": "APPROVED",
    "contract": "assinatura-8891",
    "object": "Plano Gold mensal",
    "journey": "JOURNEY_2",
    "periodicity": "MONTHLY",
    "start_date": "2026-10-01",
    "end_date": null,
    "amount": 99.9,
    "min_amount": null,
    "retry_policy": "ALLOWS_3R_7D",
    "transaction_id": "assinatura-8891"
  }
}

Charge event body

resource: "charge". Same envelope, plus the charge block. Example of charge.expired:

{
  "id": 987654321,
  "transaction_id": "assinatura-8891-2026-11-01",
  "amount": 99.9,
  "status": "ACTIVE",
  "created_at": "2026-10-27T06:00:00.000Z",
  "type": "automatic_pix",
  "resource": "charge",
  "event": "expired",
  "method": "pix",
  "currency": "BRL",
  "external_id": "RR9012345620260922f3a1c7b28e4",
  "name": "Maria Silva",
  "document_number": "12345678909",
  "recurrence": {
    "recurrence_id": "RR9012345620260922f3a1c7b28e4",
    "status": "APPROVED",
    "contract": "assinatura-8891",
    "object": "Plano Gold mensal",
    "journey": "JOURNEY_2",
    "periodicity": "MONTHLY",
    "start_date": "2026-10-01",
    "end_date": null,
    "amount": 99.9,
    "min_amount": null,
    "retry_policy": "ALLOWS_3R_7D",
    "transaction_id": "assinatura-8891"
  },
  "charge": {
    "charge_id": "7f3c1a5e9b204d68a1c4e7f0b3d69258",
    "status": "ACTIVE",
    "due_date": "2026-11-03",
    "amount": 99.9,
    "attempt_count": 1,
    "last_attempt_status": "EXPIRED",
    "end_to_end_id": null,
    "transaction_id": "assinatura-8891-2026-11-01"
  }
}

Fields

Field	Type	Description
`id`	integer	Recurrence event: internal id of the recurrence. Charge event: deposit id of the charge, the same as in the paid deposit callback.
`transaction_id`	string	Recurrence: the `transaction_id` sent on creation. Charge: `<recurrence transaction_id>-<nominal due date YYYY-MM-DD>`.
`amount`	number	Amount of the recurrence or the charge, in reais.
`status`	string	Status of the resource at the time of the event.
`created_at`	string	Creation date of the resource (ISO 8601, UTC).
`type`	string	Always `automatic_pix`.
`resource`	string	`recurrence` or `charge`.
`event`	string	What happened: `created`, `approved`, `rejected`, `expired`, `cancelled`, `scheduled` or `retry_scheduled`.
`method`	string	Always `pix`.
`currency`	string	Always `BRL`.
`external_id`	string	The recurrence's `recurrence_id`.
`name`	string	Payer name.
`document_number`	string	Payer CPF/CNPJ.
`recurrence`	object	The recurrence: `recurrence_id`, `status`, `contract`, `object`, `journey`, `periodicity`, `start_date`, `end_date`, `amount`, `min_amount`, `retry_policy`, `transaction_id`.
`charge`	object	Only on charge events: `charge_id`, `status`, `due_date`, `amount`, `attempt_count`, `last_attempt_status`, `end_to_end_id`, `transaction_id`.

Each event carries the status of the moment it happened. A recurrence.created arrives with "status": "CREATED" even if delivery is delayed and the payer has authorized in the meantime. On charge events, the top-level status and the one in charge are the event's; the status inside recurrence is the recurrence's current one.

Charges Walkthrough