Automatic Pix
Solicitations

Authorization solicitations

These endpoints only matter if you chose the notification route (journey 1): instead of showing a QR code, you ask the payer's institution to alert them in their banking app to authorize the recurrence. If you use the QR code, you can skip this page.

Available Endpoints

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

How it works

⚠️

The solicitation status describes the path of the alert, not the payer's decision. RECEIVED means the bank received it, not that the payer authorized. The authorization appears in the recurrence status, which moves to APPROVED or REJECTED.

Create solicitation

Asks the payer's institution to alert them to authorize the recurrence. There is one active solicitation at a time per recurrence.

Route

POST /v2/automatic-pix/solicitations

Headers

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

Body

ParameterTypeRequiredDescription
recurrence_idstringYesThe recurrence to be authorized. It must exist and belong to your account.
expires_atstring (ISO 8601)YesUntil when the solicitation is valid, with time zone (e.g. "2026-10-10T00:00:00-03:00" or "2026-10-10T03:00:00Z"). Once the deadline passes with no answer, the recurrence moves to EXPIRED.
destinationobjectYesThe payer's account that will receive the alert.
destination.agencystringYesBranch, up to 4 characters, without check digit.
destination.accountstringYesAccount, up to 20 characters.
destination.document_numberstringYesAccount holder's CPF (11) or CNPJ (14), digits only. The check digit is validated.
destination.ispbstringYesISPB of the payer's institution: exactly 8 digits. It is the Banco Central code that identifies the institution, not the bank number (e.g. 60701190, not 341). A wrong ISPB produces an alert that never arrives.

Request example:

curl --location 'https://api.pixtopay.com.br/v2/automatic-pix/solicitations' \
--header 'Authorization: API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
    "recurrence_id": "RR9012345620260922f3a1c7b28e4",
    "expires_at": "2026-10-10T00:00:00Z",
    "destination": {
        "agency": "0001",
        "account": "123456",
        "document_number": "12345678909",
        "ispb": "60701190"
    }
}'

Response model [2xx]

ParameterTypeDescription
solicitation_idstringSolicitation identifier
recurrence_idstringThe recurrence the solicitation belongs to
statusstringCREATED, SENT, RECEIVED or CANCELLED

Response 201:

{
  "solicitation_id": "SR9012345620260922c4d5e6f7a8b",
  "recurrence_id": "RR9012345620260922f3a1c7b28e4",
  "status": "CREATED"
}

Response 404:

{
  "message": "Recurrence not found"
}

Response 400 invalid ISPB:

{
  "type": "ValidationError",
  "message": "body.destination.ispb must be exactly 8 characters"
}

Get solicitation

Gets the current state of a solicitation.

Route

GET /v2/automatic-pix/solicitations/:solicitation_id

Headers

{
  "Authorization": "YOUR_API_KEY"
}

Request example:

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

Response 200:

{
  "solicitation_id": "SR9012345620260922c4d5e6f7a8b",
  "recurrence_id": "RR9012345620260922f3a1c7b28e4",
  "status": "RECEIVED"
}

Response 404:

{
  "message": "Solicitation not found"
}

Cancel solicitation

Cancels a solicitation that has not been answered yet. Only cancellation is accepted, and the status field is required. Cancelling the solicitation does not cancel the recurrence.

Route

PATCH /v2/automatic-pix/solicitations/:solicitation_id

Headers

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

Body

ParameterTypeRequiredDescription
statusstringYesCANCELLED

Request example:

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

Response 200:

{
  "solicitation_id": "SR9012345620260922c4d5e6f7a8b",
  "recurrence_id": "RR9012345620260922f3a1c7b28e4",
  "status": "CANCELLED"
}

Response 400 invalid status:

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