Create payment (Cash-out/Payout)

In this section, you will learn how to create payments via PIX using the PixToPay API.

Available Endpoints

Sandbox PIX key: https://sandbox.pixtopay.com.br/v2/payout/pix
Production PIX key: https://api.pixtopay.com.br/v2/payout/pix
Sandbox bank details: https://sandbox.pixtopay.com.br/v2/payout
Production bank details: https://api.pixtopay.com.br/v2/payout

Create payment via PIX (recommended)

Create an instant PIX payment using a PIX key as the destination.

Route

POST /v2/payout/pix

Headers

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

Body Parameters

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	Payment amount in reais (e.g. 150.75)
`name`	string	Yes	Beneficiary full name
`document_type`	string	Yes	Beneficiary document type (`"CPF"` or `"CNPJ"`)
`document_number`	string	Yes	Beneficiary document number (digits only)
`pix_key`	string	Yes	Beneficiary PIX key (CPF/CNPJ, email, phone, or random key)
`phone_number`	string	No	Beneficiary phone number in international format (e.g. `"5547999999999"`)
`email`	string	No	Beneficiary email address
`webhook`	string	No	URL to receive payment status notifications via webhook

Accepted PIX key formats

CPF/CNPJ: Digits only (e.g. "12345678900")
Email: Valid email address (e.g. "email@example.com")
Phone: International format with +55 (e.g. "+5547999999999")
Random key (EVP): UUID key generated by the bank (e.g. "123e4567-e89b-12d3-a456-426614174000")

Request example

curl --location 'https://sandbox.pixtopay.com.br/v2/payout/pix' \
--header 'Authorization: API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
    "transaction_id": "9233a90c-c4a8-4a3f-8da4-d77b7d0d3327",
    "name": "Daniel Menegasso",
    "document_type": "CPF",
    "document_number": "12345678900",
    "currency": "BRL",
    "amount": 1500,
    "pix_key": "email@example.com",
    "webhook": "https://webhook.site/785a3e4e-e444-4838-9c31-1c62fe4d276e"
}'

Response `200` - Success

{
  "id": 796,
  "transaction_id": "9233a90c-c4a8-4a3f-8da4-d77b7d0d3327",
  "status": 0,
  "currency": "BRL",
  "amount": 1500,
  "bank": {
    "type": "email",
    "bank_name": "COOPERATIVA DE CRÉDITO, POUPANÇA E INVESTIMENTO FRONTEIRAS DO PARANÁ",
    "ispb": "82527557",
    "account_agency": "3879",
    "account_number": "7716539016157248"
  }
}

Response Fields

Parameter	Type	Description
`id`	integer	Internal payment ID generated by PixToPay
`transaction_id`	string	Unique transaction identifier on your platform
`status`	integer	Current payment status (0 = created)
`currency`	string	Transaction currency
`amount`	number	Payment amount
`bank`	object	Destination account information identified from the PIX key
`bank.type`	string	PIX key type used
`bank.bank_name`	string	Destination bank name
`bank.ispb`	string	Destination bank ISPB
`bank.account_agency`	string	Destination account branch
`bank.account_number`	string	Destination account number

Response `400` - Missing PIX key

{
  "type": "ValidationError",
  "message": "body.pix_key is a required field"
}

Response `400` - Duplicate transaction_id

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

Create payment via bank details

Create a PIX payment using full bank account details instead of a PIX key.

Route

POST /v2/payout

Headers

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

Body Parameters

Parameter	Type	Required	Description
`transaction_id`	string	Yes	Unique transaction identifier on your platform
`currency`	string	Yes	Transaction currency (only `"BRL"` is supported)
`amount`	number	Yes	Payment amount in reais
`name`	string	Yes	Beneficiary full name
`document_type`	string	Yes	Beneficiary document type (`"CPF"` or `"CNPJ"`)
`document_number`	string	Yes	Beneficiary document number (digits only)
`bank`	object	Yes	Object containing bank information
`bank.type`	string	Yes	Transfer type: `"PIX"`
`bank.bank_name`	string	No	Bank name (optional but recommended)
`bank.ispb`	string	Yes	Bank ISPB — 8 digits
`bank.account_agency`	string	Yes	Branch number (4 digits)
`bank.account_number`	string	Yes	Account number with check digit (e.g. `"12345-6"`)
`phone_number`	string	No	Beneficiary phone number
`email`	string	No	Beneficiary email address
`webhook`	string	No	URL to receive status notifications

Request example

curl --location 'https://sandbox.pixtopay.com.br/v2/payout' \
--header 'Authorization: API_KEY' \
--header 'Content-Type: application/json' \
--data '{
    "transaction_id": "c5d81228-6d97-4b49-835a-d29eeeea7025",
    "name": "Daniel Menegasso",
    "document_type": "CPF",
    "document_number": "12345678900",
    "currency": "BRL",
    "amount": 300,
    "bank": {
        "type": "PIX",
        "bank_name": "Banco do Brasil S.A",
        "ispb": "00000000",
        "account_agency": "1234",
        "account_number": "12345-6"
    },
    "phone_number": "47999999999",
    "email": "email@example.com",
    "webhook": "https://webhook.site/c154fa95-701c-4bc1-b6e7-a4ba0e0c01c7"
}'

Response `200` - Success

{
  "id": 686,
  "transaction_id": "c5d81228-6d97-4b49-835a-d29eeeea7025",
  "status": 0,
  "currency": "BRL",
  "amount": 300,
  "bank": {
    "type": "PIX",
    "bank_name": "Banco do Brasil S.A",
    "ispb": "00000000",
    "account_agency": "1234",
    "account_number": "12345-6"
  }
}

Response `400` - Missing ISPB

{
  "type": "ValidationError",
  "message": "body.bank.ispb is required when type is PIX"
}

Response `400` - Branch length exceeded

{
  "type": "ValidationError",
  "message": "body.bank.account_agency must be at most 4 characters"
}

Important Notes

✅ Simple: Only requires the PIX key
✅ Instant: Processing in seconds
✅ 24/7: Available at any time
✅ Automatic validation: The API validates the PIX key and returns bank details

Payment Status

After creating a payment, it goes through the following statuses:

Status	Description
`0`	Payment created, awaiting processing
`1`	Payment paid / completed
`2`	Payment rejected
`3`	Payment refunded

Status flow

The status flow for a payout follows the sequence below:

0 (Created) → 1 (Paid)
0 (Created) → 2 (Rejected)
0 (Created) → 1 (Paid) → 3 (Refunded)

Sandbox Mode

In the sandbox environment, you can simulate different behaviors:

Simulating payout statuses

Add the x-sandbox-behaviour header to your request with one of the following values:

Value	Description
`paid`	Simulates an approved/completed payout (status `1`)
`rejected`	Simulates a rejected payout (status `2`)
`refunded`	Simulates a refunded payout (status `3`)

Request example with x-sandbox-behaviour:

curl --location 'https://sandbox.pixtopay.com.br/v2/payout/pix' \
--header 'Authorization: API_KEY' \
--header 'Content-Type: application/json' \
--header 'x-sandbox-behaviour: paid' \
--data-raw '{
    "transaction_id": "9233a90c-c4a8-4a3f-8da4-d77b7d0d3327",
    "name": "Daniel Menegasso",
    "document_type": "CPF",
    "document_number": "12345678900",
    "currency": "BRL",
    "amount": 1500,
    "pix_key": "email@example.com",
    "webhook": "https://webhook.site/785a3e4e-e444-4838-9c31-1c62fe4d276e"
}'

Cash-Out Search Payments

Create payment (Cash-out/Payout)

Available Endpoints

Create payment via PIX (recommended)

Route

Headers

Body Parameters

Accepted PIX key formats

Request example

Response 200 - Success

Response Fields

Response 400 - Missing PIX key

Response 400 - Duplicate transaction_id

Create payment via bank details

Route

Headers

Body Parameters

Request example

Response 200 - Success

Response 400 - Missing ISPB

Response 400 - Branch length exceeded

Important Notes

Payment Status

Status flow

Sandbox Mode

Simulating payout statuses

Request example with x-sandbox-behaviour:

Response `200` - Success

Response `400` - Missing PIX key

Response `400` - Duplicate transaction_id

Response `200` - Success

Response `400` - Missing ISPB

Response `400` - Branch length exceeded