Consultar cobranças PIX
Nesta seção, você aprenderá como consultar cobranças PIX (cash-in) criadas usando a API PixToPay.
Endpoints Disponíveis
- Sandbox:
https://sandbox.pixtopay.com.br/v2/transactions - Produção:
https://api.pixtopay.com.br/v2/transactions
Consultar cobrança por ID
Consulte uma cobrança específica usando o ID interno gerado pela PixToPay.
Route
GET /v2/transactions?id={ID}
Headers
{
"Authorization": "YOUR_API_KEY"
}Query Parameters
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
id | integer | Sim | ID interno da cobrança gerado pela PixToPay |
Exemplo de requisição:
curl --location 'https://sandbox.pixtopay.com.br/v2/transactions?id=59276' \
--header 'Authorization: API_KEY'Resposta 200 - Sucesso:
{
"id": 59276,
"transaction_id": "12345678933",
"name": "DANIEL MENEGASSO",
"document_number": "00000000000",
"document_type": "CPF",
"currency": "BRL",
"amount": 145,
"status": 1,
"pix": {
"due": "2021-11-26T15:50:00.000Z",
"qrcode": "00020101021226890014br.gov.bcb.pix2567invoice-h.sandbox.starkbank.com/v2/efaf9f5a43b94a93a0b845050435864b5204000053039865802BR5925Pay42 Intermediacao De Ne6010Porto Belo62070503***6304E3E5"
},
"webhook": "https://webhook.site/c154fa95-701c-4bc1-b6e7-a4ba0e0c01c7",
"created_at": "2021-11-26T15:02:55.000Z",
"paid_at": "2021-11-26T15:10:16.000Z"
}Campos da Resposta
| Parâmetro | Tipo | Descrição |
|---|---|---|
id | integer | ID interno da cobrança gerado pela PixToPay |
transaction_id | string | Identificador único da transação na sua plataforma |
name | string | Nome do pagador |
document_number | string | Número do documento do pagador |
document_type | string | Tipo do documento ("CPF" ou "CNPJ") |
currency | string | Moeda da transação (sempre "BRL") |
amount | number | Valor da cobrança em reais |
status | integer | Status atual da cobrança (ver tabela de status) |
pix | object | Objeto contendo informações do PIX |
pix.due | string | Data e hora de expiração da cobrança |
pix.qrcode | string | Código QR da cobrança PIX |
webhook | string | URL do webhook configurado |
created_at | string | Data e hora de criação da cobrança |
paid_at | string | Data e hora do pagamento (se já foi pago) |
Consultar cobrança por transaction_id
Consulte uma cobrança específica usando o transaction_id da sua plataforma.
Route
GET /v2/transactions?transaction_id={TRANSACTION_ID}
Headers
{
"Authorization": "YOUR_API_KEY"
}Query Parameters
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
transaction_id | string | Sim | Identificador único da transação na sua plataforma |
Exemplo de requisição:
curl --location 'https://sandbox.pixtopay.com.br/v2/transactions?transaction_id=12345678933' \
--header 'Authorization: API_KEY'Resposta 200 - Sucesso:
Retorna o mesmo formato da consulta por ID.
Consultar cobranças por período
Liste cobranças criadas em um período específico, com opção de filtrar por status e paginar os resultados.
Route
GET /v2/transactions/period
Headers
{
"Authorization": "YOUR_API_KEY"
}Query Parameters
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
start | string | Sim | Data inicial do período (formato: "YYYY-MM-DD HH:MM:SS") |
end | string | Sim | Data final do período (formato: "YYYY-MM-DD HH:MM:SS") |
page | integer | Não | Número da página (padrão: 1) |
size | integer | Não | Quantidade de registros por página (máximo: 100) |
status | integer | Não | Filtrar por status específico (0, 1, 2, 3 ou 4) |
Exemplo de requisição:
curl --location 'https://sandbox.pixtopay.com.br/v2/transactions/period?start=2022-10-01%2012:00:00&end=2022-10-31%2012:00:00&page=1&size=10&status=1' \
--header 'Authorization: API_KEY'Resposta 200 - Sucesso:
{
"data": [
{
"id": 23589,
"transaction_id": "c5d81228-6d97-4b49-835a-d29eeeea7025",
"name": "Daniel Menegasso",
"document_number": "00000000000",
"document_type": "CPF",
"currency": "BRL",
"amount": 1.02,
"status": 1,
"pix": {
"due": "2024-12-30T17:00:00.000Z",
"qrcode": "00020101021226890014br.gov.bcb.pix2567brcode-h.sandbox.starkinfra.com/v2/4e093f699bf746e3824bf61abb6a9d855204000053039865802BR5925Bpay Solucoes de Pagament6015Balneario Cambo62070503***6304A308"
},
"webhook": "https://webhook.site/1729bf83-5b8e-46fe-b125-1ef5932f4fef",
"created_at": "2024-07-15T20:12:52.000Z",
"paid_at": "2024-07-15T20:13:15.000Z"
}
],
"page": 1,
"size": 10,
"total": 1
}Campos da Resposta
| Parâmetro | Tipo | Descrição |
|---|---|---|
data | array | Array de cobranças encontradas |
page | integer | Página atual |
size | integer | Quantidade de registros por página |
total | integer | Total de cobranças encontradas |
Resposta 400 - Tamanho inválido:
{
"type": "ValidationError",
"message": "size must be less than or equal to 100"
}Resposta 400 - Data inválida:
{
"type": "ValidationError",
"message": "start date must be less than end date"
}Status de Cobranças
Os status de cobranças PIX são representados por números inteiros:
| Status | Descrição |
|---|---|
0 | Cobrança criada, aguardando pagamento |
1 | Cobrança paga |
2 | Cobrança cancelada |
3 | Cobrança expirada |
4 | Cobrança devolvida |
Exportar cobranças por período em CSV
Exporte todas cobranças em um período específico em formato CSV, esta exportação contempla todos as cobranças e todos os status, sem paginação.
Route
GET /v2/transactions/period/csv
Headers
{
"Authorization": "YOUR_API_KEY"
}Query Parameters
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
start | string | Sim | Data inicial do período (formato: "YYYY-MM-DD HH:MM:SS") |
end | string | Sim | Data final do período (formato: "YYYY-MM-DD HH:MM:SS") |
Exemplo de requisição:
curl --location 'https://sandbox.pixtopay.com.br/v2/transactions/period/csv?start=2022-10-01%2012:00:00&end=2022-10-31%2012:00:00' \
--header 'Authorization: API_KEY'Resposta 200 - Sucesso:
id,transaction_id,name,document_number,document_type,currency,amount,status,type,refund_amount,webhook,created_at,paid_at,psp_id,e2e_id,provider
654972454,brand_36084626,"John Cooper",12345678910,CPF,BRL,10,1,PIX,0,"https://api-brand.brand.com/webhook",2026-01-06T23:59:58.000Z,2026-01-07T00:00:32.000Z,98424abe7ee94a07a67a021d46e2ec0c,E22896431202601070000erwur6nszuk,STARKBANK
654972441,brand_36084625,"Bob Dylan",12345678910,CPF,BRL,15,1,PIX,0,"https://api-brand.brand.com/webhook",2026-01-06T23:59:57.000Z,2026-01-07T00:00:39.000Z,91e680eec1d74ae097fe86531d7554a9,E18236120202601070000s07386d6c27,EFIPAY
....Resposta 400 - Data inválida:
{
"type": "ValidationError",
"message": "start date must be less than end date"
}Status de Cobranças
Os status de cobranças PIX são representados por números inteiros:
| Status | Descrição |
|---|---|
0 | Cobrança criada, aguardando pagamento |
1 | Cobrança paga |
2 | Cobrança cancelada |
3 | Cobrança expirada |
4 | Cobrança devolvida |