Charges

A charge is the debit of one cycle under a recurrence that is already authorized.

The endpoints on this page let you get these charges and, when needed, cancel a specific cycle or reschedule a debit that failed.

Available Endpoints

• Production: https://api.pixtopay.com.br/v2/automatic-pix/charges

Charge model

Every endpoint on this page answers with the same object:

Activation charge. On a journey 3 recurrence, the activation payment is listed as a charge of the recurrence, with "type": "activation". It is a Pix paid on the spot: due_date is the creation day, attempts is 1 once the payer's Pix arrives and 0 before, and it cannot be cancelled or rescheduled. Its status goes from ACTIVE to SETTLED when paid, or to CANCELLED if it expires unpaid or the payment is refunded. A refunded activation reads CANCELLED with attempts: 1 and the payment's end_to_end_id.

Get charge

Gets a charge with its current state. This is the call to find out whether the debit happened.

Route

GET /v2/automatic-pix/charges/:charge_id

Headers

{
  "Authorization": "YOUR_API_KEY"
}

Request example:

curl --location 'https://api.pixtopay.com.br/v2/automatic-pix/charges/7f3c1a5e9b204d68a1c4e7f0b3d69258' \
--header 'Authorization: API_KEY'

Response 200:

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

Response 404:

{
  "message": "Charge not found"
}

The 404 covers an identifier that does not exist or that does not belong to your account.

List charges

Lists the charges created in a period. The parameters are the same as the recurrence listing.

Route

GET /v2/automatic-pix/charges

Headers

{
  "Authorization": "YOUR_API_KEY"
}

Query Parameters

Request example:

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

Response 200:

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

Cancel charge

Cancels one cycle before its due date. It is the only way to act on a charge PixToPay has already created. Only cancellation is accepted, and the status field is required.

Cancelling one cycle's charge does not cancel the recurrence: the following cycles keep being charged. To end the subscription, cancel the recurrence.

Route

PATCH /v2/automatic-pix/charges/:charge_id

Headers

{
  "Authorization": "YOUR_API_KEY",
  "Content-Type": "application/json"
}

Body

Request example:

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

Response 200:

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

Response 400 invalid status:

{
  "type": "ValidationError",
  "message": "body.status must be one of the following values: CANCELLED"
}

Reschedule a debit

Reschedules the debit of a charge that was not paid on its due date, to a date you choose.

Route

POST /v2/automatic-pix/charges/:charge_id/retry/:date

Headers

{
  "Authorization": "YOUR_API_KEY"
}

Parameters

Rules

• The recurrence must have been created with retry_policy: "ALLOWS_3R_7D". With NOT_ALLOWED there are no retries.
• At most three retries per charge.
• All within seven days of the effective due date (the charge's due_date).
• Never on the due date itself.

Call this endpoint when you want to pick the date: for example, when you know the customer's salary arrives on the 5th. The charge.retry_scheduled event confirms the rescheduling.

Request example:

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

Response 200:

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

The due_date does not change: the original due date anchors the seven-day window. What changes is attempts.

Response 400 outside the rules:

A date outside the seven-day window, on the due date itself, past the three-retry limit, or on a NOT_ALLOWED recurrence is refused by the settlement system:

{
  "type": "ProviderError",
  "message": "<reason for the refusal>"
}