Cash-in routes

In this section you will find all the endpoints needed to create, search, cancel, and manage PIX charges using the PixToPay API.

Available Endpoints

Sandbox: https://sandbox.pixtopay.com.br/v2/cashin
Production: https://api.pixtopay.com.br/v2/cashin

Create PIX charge with expiration

Route

POST /v2/pix

Headers

{
  "Authorization": "YOUR_API_KEY",
  "Content-Type": "application/json", // optional, default is application/json
  ...
}

Body

Parameter	Type	Required	Description
`transaction_id`	string	Yes	Unique transaction identifier on your platform (UUID v4 recommended)
`currency`	string	Yes	Transaction currency (only "BRL" is supported)
`amount`	number	Yes	Charge amount in reais (e.g. 150.75)
`due`	string (ISO 8601)	Yes	Charge expiration date and time (e.g. "2024-12-31T23:59:59"); always send in UTC-0 timezone
`name`	string	Yes	Payer full name
`document_type`	string	Yes	Payer document type ("CPF" or "CNPJ")
`document_number`	string	Yes	Payer document number (digits only)
`webhook`	string	Yes	URL to receive charge status notifications via webhook
`phone_number`	string	No	Payer phone number in international format (e.g. "5547999999999")
`email`	string	No	Payer email address
`external_id`	string	No	External identifier to group charges or identify users (e.g. "group_1" or "user_12345")

Request example:

curl --location 'https://sandbox.pixtopay.com.br/v2/pix' \
--header 'Authorization: API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
    "transaction_id": "5fe8e512-fa13-44e4-86b4-c557dd76e68d",
    "currency": "BRL",
    "amount": 1.02,
    "due" : "2024-12-30T14:00:00",
    "name": "NOME E SOBRENOME",
    "document_type": "CPF",
    "document_number": "12345678900",
    "webhook": "https://webhook.site/1729bf83-5b8e-46fe-b125-1ef5932f4fef",
    "phone_number": "5547999999999",
    "email": "sandbox@pixtopay.com.br",
    "external_id": "group_1",
    "base64image": true
}'

Response model [2xx]

Parameter	Type	Description
`id`	integer	Unique identifier of the generated PIX charge
`transaction_id`	string	Unique transaction identifier on your platform
`status`	integer	Current PIX charge status (see status table below)
`currency`	string	Transaction currency (always "BRL")
`amount`	number	Charge amount in reais
`due`	string (ISO 8601)	Charge expiration date and time
`qrcode`	string	PIX charge QR code for payment
`qrcode_image`	string	(Optional) QR code image in base64 format (only present if `base64image` is `true` in the body)

Response model [4xx]

Parameter	Type	Description
`type`	string	Type of error that occurred
`message`	string	Message describing the error

Response model [5xx]

Parameter	Type	Description
`message`	string	Message describing the error

Response `200`:

{
  "id": 59366,
  "transaction_id": "12345678942",
  "status": 0,
  "currency": "BRL",
  "amount": 145,
  "due": "2021-11-30T19:00:00.000Z",
  "qrcode": "00020101021226890014br.gov.bcb.pix2567invoice-h.sandbox.starkbank.com/v2/7998213473f84059983768a2b646ce6b5204000053039865802BR5925Pay42 Intermediacao De Ne6010Porto Belo62070503***6304F572"
}

Response `200` with `base64image`:

{
  "id": 23592,
  "transaction_id": "074b88a1-58ae-47b4-80c5-856ad88d2ac2",
  "status": 0,
  "currency": "BRL",
  "amount": 1.02,
  "due": "2024-12-30T17:00:00.000Z",
  "qrcode": "00020101021226890014br.gov.bcb.pix2567brcode-h.sandbox.starkinfra.com/v2/4e093f699bf746e3824bf61abb6a9d855204000053039865802BR5925Bpay Solucoes de Pagament6015Balneario Cambo62070503***6304A308",
  "qrcode_image": "data:image/png;base64,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"
}

Response `400` duplicate transaction_id:

{
  "type": "ValidationError",
  "message": "body.transaction_id already exists"
}

Response `400` invalid expiration:

{
  "type": "ValidationError",
  "message": "body.due must be greater or equal to now"
}

Response `5xx` internal error:

{
  "message": "Internal server error!"
}

PIX charge status list

PIX charge statuses are represented by integers. Below are the possible statuses for a PIX charge:

Status	Description
`0`	Charge created, awaiting payment
`1`	Charge paid
`2`	Charge cancelled
`3`	Charge expired
`4`	Charge refunded

Status flow

The status flow for a PIX charge follows the sequence below:

0 (Created) → 1 (Paid)
0 (Created) → 2 (Cancelled)
0 (Created) → 3 (Expired)
0 (Created) → 4 (Refunded)*
0 (Created) → 1 (Paid) → 4 (Refunded)

*Note: when the status changes from 0 (created) directly to 4 (refunded), this happens when the payer completes the payment but the amount is refunded for some reason (e.g. third-party payment attempt, restrictive list, etc).

Sandbox Mode

In sandbox, you can use the x-sandbox-behaviour header to force the final status of a deposit, allowing you to test each scenario without relying on specific conditions.

Simulating deposit statuses

Add the header to your request with one of the following values:

Value	Description
`paid`	Simulates a successfully paid deposit (status `1`)
`expired`	Simulates an expired deposit (status `3`)
`refunded`	Simulates a deposit refunded directly without prior payment (status `4`)
`paid_then_refunded`	Simulates a deposit that transitions from paid to refunded (status `1` → `4`)

Request example with x-sandbox-behaviour:

curl --location 'https://sandbox.pixtopay.com.br/v2/pix' \
--header 'Authorization: API_KEY' \
--header 'Content-Type: application/json' \
--header 'x-sandbox-behaviour: paid' \
--data-raw '{
    "transaction_id": "5fe8e512-fa13-44e4-86b4-c557dd76e68d",
    "currency": "BRL",
    "amount": 1.02,
    "due": "2024-12-30T14:00:00",
    "name": "NOME E SOBRENOME",
    "document_type": "CPF",
    "document_number": "12345678900",
    "webhook": "https://webhook.site/1729bf83-5b8e-46fe-b125-1ef5932f4fef"
}'

Cash-In Search Charges