Search payments (Payouts)

In this section, you will learn how to search PIX payments (cash-out/payouts) created using the PixToPay API.

Available Endpoints

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

Search payment by ID

Search for a specific payment using the internal ID generated by PixToPay.

Route

GET /v2/withdrawals?id={ID}

Headers

{
  "Authorization": "YOUR_API_KEY"
}

Query Parameters

Parameter	Type	Required	Description
`id`	integer	Yes	Internal payment ID generated by PixToPay

Request example

curl --location 'https://sandbox.pixtopay.com.br/v2/withdrawals?id=685' \
--header 'Authorization: API_KEY'

Response `200` - PIX success

{
  "id": 685,
  "transaction_id": "12345678911",
  "name": "Daniel Menegasso",
  "document_number": "00000000000",
  "document_type": "CPF",
  "currency": "BRL",
  "amount": 300,
  "status": 1,
  "bank": {
    "type": "PIX",
    "bank_name": "Banco do Brasil S.A.",
    "ispb": "00000000",
    "account_agency": "1234",
    "account_number": "12345-6"
  },
  "webhook": "https://webhook.site/c154fa95-701c-4bc1-b6e7-a4ba0e0c01c7",
  "created_at": "2021-12-01T14:48:03.000Z",
  "e2e": "E20018183202603051309eFsMqKfpFkv",
  "paid_at": "2021-12-01T14:48:08.000Z",
  "psp_id": "123321"
}

Response Fields

Parameter	Type	Description
`id`	integer	Internal payment ID generated by PixToPay
`transaction_id`	string	Unique transaction identifier on your platform
`name`	string	Beneficiary name
`document_number`	string	Beneficiary document number
`document_type`	string	Document type (`"CPF"` or `"CNPJ"`)
`currency`	string	Transaction currency (always `"BRL"`)
`amount`	number	Payment amount in reais
`status`	integer	Current payment status (see status table)
`bank`	object	Object containing bank information
`bank.type`	string	Transfer type (`"PIX"`)
`bank.ispb`	string	Bank ISPB
`bank.account_agency`	string	Destination account branch
`bank.account_number`	string	Destination account number
`webhook`	string	Configured webhook URL
`created_at`	string	Payment creation date and time
`paid_at`	string	Payment completion date and time (if already processed)

Search payment by transaction_id

Search for a specific payment using your platform's transaction_id.

Route

GET /v2/withdrawals?transaction_id={TRANSACTION_ID}

Headers

{
  "Authorization": "YOUR_API_KEY"
}

Query Parameters

Parameter	Type	Required	Description
`transaction_id`	string	Yes	Unique transaction identifier on your platform

Request example

curl --location 'https://sandbox.pixtopay.com.br/v2/withdrawals?transaction_id=12345678911' \
--header 'Authorization: API_KEY'

Response `200` - Success

Returns the same format as search by ID.

Search payments by period

List payments created in a specific period, with optional status filter and pagination.

Route

GET /v2/withdrawals/period

Headers

{
  "Authorization": "YOUR_API_KEY"
}

Query Parameters

Parameter	Type	Required	Description
`start`	string	Yes	Period start (format: `"YYYY-MM-DD HH:MM:SS"`)
`end`	string	Yes	Period end (format: `"YYYY-MM-DD HH:MM:SS"`)
`page`	integer	No	Page number (default: 1)
`size`	integer	No	Records per page (maximum: 100)
`status`	integer	No	Filter by specific status (0, 1, 2, 3, or 4)

Request example

curl --location 'https://sandbox.pixtopay.com.br/v2/withdrawals/period?start=2025-12-09%2021:00:00&end=2025-12-10%2020:59:59&size=100&page=1&status=1' \
--header 'Authorization: API_KEY'

Response `200` - Success

{
  "count_data": 2,
  "page": 1,
  "size": 100,
  "count_pages": 1,
  "data": [
    {
      "id": 123456788,
      "transaction_id": "brand_123456788",
      "name": "John Cena",
      "document_number": "12345678910",
      "document_type": "CPF",
      "currency": "BRL",
      "amount": 150,
      "status": 1,
      "bank": {
        "type": "PIX",
        "ispb": "08561701",
        "account_agency": "1",
        "account_number": "133194936"
      },
      "webhook": "https://webhook.site/bfc4df9d-e4a7-4147-85a8-f61cf1d84f82",
      "created_at": "2025-12-11T02:59:57.000Z",
      "paid_at": "2025-12-11T03:00:00.000Z",
      "e2e": "E09089356202512110259API839d33c0",
      "psp_id": "123456788"
    },
    {
      "id": 123456789,
      "transaction_id": "brand_123456789",
      "name": "John Cena",
      "document_number": "12345678910",
      "document_type": "CPF",
      "currency": "BRL",
      "amount": 60,
      "status": 1,
      "bank": {
        "type": "PIX",
        "ispb": "60746948",
        "account_agency": "6638",
        "account_number": "1326821"
      },
      "webhook": "https://webhook.site/bfc4df9d-e4a7-4147-85a8-f61cf1d84f82",
      "created_at": "2025-12-11T02:59:48.000Z",
      "paid_at": "2025-12-11T02:59:51.000Z",
      "e2e": "E09089356202512110259API00bec24b",
      "psp_id": "100247168"
    }
  ]
}

Response Fields

Parameter	Type	Description
`count_data`	integer	Total payments found
`page`	integer	Current page
`size`	integer	Records per page
`count_pages`	integer	Total pages
`data`	array	Array of payments found

Response `400` - Invalid size

{
  "type": "ValidationError",
  "message": "size must be less than or equal to 100"
}

Response `400` - Invalid date

{
  "type": "ValidationError",
  "message": "start date must be less than end date"
}

Search payments by customer

List all payments made to a specific customer using the document number.

Route

GET /v2/withdrawals/customer?document_number={DOCUMENT_NUMBER}

Headers

{
  "Authorization": "YOUR_API_KEY"
}

Query Parameters

Parameter	Type	Required	Description
`document_number`	string	Yes	Beneficiary document number (CPF or CNPJ)

Request example

curl --location 'https://sandbox.pixtopay.com.br/v2/withdrawals/customer?document_number=12345678900' \
--header 'Authorization: API_KEY'

Response `200` - Success

{
  "data": [
    {
      "id": 685,
      "transaction_id": "12345678911",
      "name": "Daniel Menegasso",
      "document_number": "12345678900",
      "document_type": "CPF",
      "currency": "BRL",
      "amount": 300,
      "status": 1,
      "bank": {
        "type": "PIX",
        "ispb": "00000000",
        "account_agency": "1234",
        "account_number": "12345-6"
      },
      "created_at": "2021-12-01T14:48:03.000Z",
      "paid_at": "2021-12-01T14:48:08.000Z"
    },
  ],
  "total": 1
}

Response Fields

Parameter	Type	Description
`data`	array	Array of payments found
`total`	integer	Total payments found for the customer

Response `400` - Invalid document

{
  "type": "ValidationError",
  "message": "document_number is invalid"
}

Response `404` - No payments found

{
  "message": "No withdrawals found for this customer"
}

Payment Statuses

Payment statuses are represented by integers:

Status	Description
`0`	Payment created, awaiting processing
`1`	Payment approved / completed
`2`	Payment canceled
`3`	Payment rejected
`4`	Payment processing

Important Notes

Unique IDs: Both id and transaction_id are unique and can be used for lookup
Full history: Customer search returns the full payment history
Webhook: Using webhooks is recommended for automatic status updates
Cache: Data may have a short delay (a few seconds) after creation

Search payments by period (CSV)

List payments in a specific period in CSV format; this export includes all payments and all statuses, without pagination.

Route

GET /v2/withdrawals/period/csv

Headers

{
  "Authorization": "YOUR_API_KEY"
}

Query Parameters

Parameter	Type	Required	Description
`start`	string	Yes	Period start (format: `"YYYY-MM-DD HH:MM:SS"`)
`end`	string	Yes	Period end (format: `"YYYY-MM-DD HH:MM:SS"`)

Request example

curl --location 'https://sandbox.pixtopay.com.br/v2/withdrawals/period/csv?start=2025-12-09%2021:00:00&end=2025-12-10%2020:59:59' \
--header 'Authorization: API_KEY'

Response `200` - Success

id,transaction_id,name,document_number,document_type,currency,amount,status,bank_type,bank_name,bank_code,account_agency,account_number,webhook,created_at,paid_at,e2e,psp_id,provider
99451160,brand_7348442,"John Cooper",12345678910,CPF,BRL,200,1,PIX,"NU PAGAMENTOS S.A. - INSTITUIÇÃO DE PAGAMENTO",18236120,1,123456,"https://api-brand.brand.com/webhook",2025-11-30T20:59:54.000Z,2025-12-01T00:00:01.000Z,E200181832025113023597KWFHMmLqtD,4808268973604864,STARKBANK
99451156,brand_7348440,"Bob Dylan",12345678910,CPF,BRL,100,1,PIX,"NU PAGAMENTOS - IP",18236120,1,987654321,"https://api-brand.brand.com/webhook",2025-11-30T20:59:48.000Z,2025-11-30T23:59:52.000Z,E09089356202511302359API37fdec9d,99451156,EFIPAY
...

Response `400` - Invalid date

{
  "type": "ValidationError",
  "message": "start date must be less than end date"
}

Payment Statuses

Payment statuses are represented by integers:

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

Create Payment PDF Receipt

Search payments (Payouts)

Available Endpoints

Search payment by ID

Route

Headers

Query Parameters

Request example

Response 200 - PIX success

Response Fields

Search payment by transaction_id

Route

Headers

Query Parameters

Request example

Response 200 - Success

Search payments by period

Route

Headers

Query Parameters

Request example

Response 200 - Success

Response Fields

Response 400 - Invalid size

Response 400 - Invalid date

Search payments by customer

Route

Headers

Query Parameters

Request example

Response 200 - Success

Response Fields

Response 400 - Invalid document

Response 404 - No payments found

Payment Statuses

Important Notes

Search payments by period (CSV)

Route

Headers

Query Parameters

Request example

Response 200 - Success

Response 400 - Invalid date

Payment Statuses

Response `200` - PIX success

Response `200` - Success

Response `200` - Success

Response `400` - Invalid size

Response `400` - Invalid date

Response `200` - Success

Response `400` - Invalid document

Response `404` - No payments found

Response `200` - Success

Response `400` - Invalid date