Complete walkthrough

Scenario: a store sells the "Plano Gold", a monthly subscription of R$ 99.90, charged on the 1st of every month, with QR code authorization at checkout.

Create the recurrence

curl --location 'https://api.pixtopay.com.br/v2/automatic-pix/recurrences' \
--header 'Authorization: API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
    "transaction_id": "assinatura-8891",
    "object": "Plano Gold mensal",
    "debtor": {
        "document_number": "12345678909",
        "name": "Maria Silva",
        "email": "maria.silva@exemplo.com.br"
    },
    "schedule": {
        "start_date": "2026-10-01",
        "periodicity": "MONTHLY"
    },
    "amount": 99.90,
    "retry_policy": "ALLOWS_3R_7D",
    "business_day_adjust": true,
    "webhook": "https://loja.exemplo.com.br/callbacks/pixtopay"
}'

Response 201:

{
  "recurrence_id": "RR9012345620260922f3a1c7b28e4",
  "status": "CREATED",
  "contract": "assinatura-8891",
  "debtor": { "document_number": "12345678909", "name": "Maria Silva" },
  "schedule": {
    "start_date": "2026-10-01",
    "end_date": null,
    "periodicity": "MONTHLY"
  },
  "amount": 99.9,
  "retry_policy": "ALLOWS_3R_7D",
  "business_day_adjust": true,
  "charge_lead_days": 5,
  "journey": "AWAITING_DEFINITION",
  "pix_copy_paste": "00020126850014br.gov.bcb.pix2563qrcode.exemplo/v2/9f2a...6304A1B2",
  "qrcode": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUg...",
  "webhook": "https://loja.exemplo.com.br/callbacks/pixtopay"
}

Store the recurrence_id. end_date came back null because the subscription is open-ended.

Show the QR code

Show qrcode as an image and pix_copy_paste as copyable text. Both carry the same thing; the payer uses whichever is more convenient. Maria opens her banking app, scans and authorizes.

Confirm the authorization

recurrence.approved arrives at your webhook. Confirm it by getting the recurrence:

curl --location 'https://api.pixtopay.com.br/v2/automatic-pix/recurrences/RR9012345620260922f3a1c7b28e4' \
--header 'Authorization: API_KEY'

{
  "recurrence_id": "RR9012345620260922f3a1c7b28e4",
  "status": "APPROVED",
  "journey": "JOURNEY_2",
  "...": "..."
}

APPROVED: activate Maria's plan in your system. From here on, PixToPay creates each cycle's charge on its own, 5 days before the due date (the charge_lead_days default).

PixToPay creates the cycle's charge

The nominal due date of the first cycle is 2026-11-01. On 2026-10-27 (D-5), PixToPay creates the charge and you receive charge.created, already carrying the charge_id. To check by query:

curl --location 'https://api.pixtopay.com.br/v2/automatic-pix/charges?start=2026-10-27T00:00:00Z&end=2026-10-28T00:00:00Z' \
--header 'Authorization: API_KEY'

{
  "pagination": { "current_page": 0, "page_size": 100, "total_pages": 1, "total_items": 1 },
  "charges": [
    {
      "recurrence_id": "RR9012345620260922f3a1c7b28e4",
      "charge_id": "7f3c1a5e9b204d68a1c4e7f0b3d69258",
      "type": "cycle",
      "status": "CREATED",
      "amount": 99.9,
      "due_date": "2026-11-03",
      "attempts": 0,
      "end_to_end_id": null
    }
  ]
}

Since the recurrence was created with business_day_adjust: true, the charge falls due on November 3, 2026, the first business day after November 1. Shortly after, charge.scheduled arrives: Maria's bank scheduled the debit, and the charge is ACTIVE.

The debit fails

On the 3rd, Maria has no funds. charge.expired arrives. The charge stays ACTIVE: what failed was the attempt, not the charge.

{
  "recurrence_id": "RR9012345620260922f3a1c7b28e4",
  "charge_id": "7f3c1a5e9b204d68a1c4e7f0b3d69258",
  "type": "cycle",
  "status": "ACTIVE",
  "amount": 99.9,
  "due_date": "2026-11-03",
  "attempts": 1,
  "end_to_end_id": null
}

Reschedule

The recurrence was created with ALLOWS_3R_7D: there are up to three retries within seven days of the due date. Maria's salary arrives on the 5th, so the store picks the 6th:

curl --location --request POST 'https://api.pixtopay.com.br/v2/automatic-pix/charges/7f3c1a5e9b204d68a1c4e7f0b3d69258/retry/2026-11-06' \
--header 'Authorization: API_KEY'

charge.retry_scheduled arrives.

The charge is paid

On the 6th the debit goes through. The paid deposit callback arrives ("type": "transaction", "status": 1), with transaction_id equal to assinatura-8891-2026-11-01. It is what confirms the money. Getting the charge:

{
  "recurrence_id": "RR9012345620260922f3a1c7b28e4",
  "charge_id": "7f3c1a5e9b204d68a1c4e7f0b3d69258",
  "type": "cycle",
  "status": "SETTLED",
  "amount": 99.9,
  "due_date": "2026-11-03",
  "attempts": 2,
  "end_to_end_id": "E6070119020261106093000a1b2c3d4"
}

November is paid. In December, PixToPay repeats step 4 on its own. Nothing needs to be authorized again and no call is needed.

End the subscription

When Maria cancels her plan:

curl --location --request PATCH 'https://api.pixtopay.com.br/v2/automatic-pix/recurrences/RR9012345620260922f3a1c7b28e4' \
--header 'Authorization: API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
    "status": "CANCELLED"
}'

recurrence.cancelled arrives. If a charge was already issued and not yet debited, and you do not want to collect it, cancel it too with PATCH /charges/:charge_id.

Notifications Errors