Cash-Out
Consultar Pagamento

Consultar pagamentos (Payouts)

Nesta seção, você aprenderá como consultar pagamentos PIX e TED (cash-out/payouts) criados usando a API PixToPay.

Endpoints Disponíveis

  • Sandbox: https://sandbox.pixtopay.com.br/v2/withdrawals
  • Produção: https://api.pixtopay.com.br/v2/withdrawals

Consultar pagamento por ID

Consulte um pagamento específico usando o ID interno gerado pela PixToPay.

Route

GET /v2/withdrawals?id={ID}

Headers

{
  "Authorization": "YOUR_API_KEY"
}

Query Parameters

ParâmetroTipoObrigatórioDescrição
idintegerSimID interno do pagamento gerado pela PixToPay

Exemplo de requisição:

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

Resposta 200 - Sucesso PIX:

{
  "id": 685,
  "transaction_id": "12345678911",
  "name": "Daniel Menegasso",
  "document_number": "00000000000",
  "document_type": "CPF",
  "currency": "BRL",
  "amount": 300,
  "status": 1,
  "bank": {
    "type": "PIX",
    "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",
  "paid_at": "2021-12-01T14:48:08.000Z"
}

Resposta 200 - Sucesso TED:

{
  "id": 686,
  "transaction_id": "12345678912",
  "name": "Daniel Menegasso",
  "document_number": "00000000000",
  "document_type": "CPF",
  "currency": "BRL",
  "amount": 300,
  "status": 1,
  "bank": {
    "type": "TED",
    "bank_code": "001",
    "account_agency": "1234",
    "account_number": "12345-5"
  },
  "webhook": "https://webhook.site/c154fa95-701c-4bc1-b6e7-a4ba0e0c01c7",
  "created_at": "2021-12-01T16:40:13.000Z",
  "paid_at": "2021-12-02T11:16:33.000Z"
}

Campos da Resposta

ParâmetroTipoDescrição
idintegerID interno do pagamento gerado pela PixToPay
transaction_idstringIdentificador único da transação na sua plataforma
namestringNome do beneficiário
document_numberstringNúmero do documento do beneficiário
document_typestringTipo do documento ("CPF" ou "CNPJ")
currencystringMoeda da transação (sempre "BRL")
amountnumberValor do pagamento em reais
statusintegerStatus atual do pagamento (ver tabela de status)
bankobjectObjeto contendo informações bancárias
bank.typestringTipo de transferência ("PIX" ou "TED")
bank.ispbstringISPB do banco (presente em pagamentos PIX)
bank.bank_codestringCódigo do banco (presente em pagamentos TED)
bank.account_agencystringAgência da conta de destino
bank.account_numberstringNúmero da conta de destino
webhookstringURL do webhook configurado
created_atstringData e hora de criação do pagamento
paid_atstringData e hora da conclusão do pagamento (se já foi processado)

Consultar pagamento por transaction_id

Consulte um pagamento específico usando o transaction_id da sua plataforma.

Route

GET /v2/withdrawals?transaction_id={TRANSACTION_ID}

Headers

{
  "Authorization": "YOUR_API_KEY"
}

Query Parameters

ParâmetroTipoObrigatórioDescrição
transaction_idstringSimIdentificador único da transação na sua plataforma

Exemplo de requisição:

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

Resposta 200 - Sucesso:

Retorna o mesmo formato da consulta por ID.

Consultar pagamentos por período

Liste pagamentos criados em um período específico, com opção de filtrar por status e paginar os resultados.

Route

GET /v2/withdrawals/period

Headers

{
  "Authorization": "YOUR_API_KEY"
}

Query Parameters

ParâmetroTipoObrigatórioDescrição
startstringSimData inicial do período (formato: "YYYY-MM-DD HH:MM:SS")
endstringSimData final do período (formato: "YYYY-MM-DD HH:MM:SS")
pageintegerNãoNúmero da página (padrão: 1)
sizeintegerNãoQuantidade de registros por página (máximo: 100)
statusintegerNãoFiltrar por status específico (0, 1, 2, 3 ou 4)

Exemplo de requisição:

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'

Resposta 200 - Sucesso:

{
  "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"
    }
  ]
}

Campos da Resposta

ParâmetroTipoDescrição
count_dataintegerTotal de pagamentos encontrados
pageintegerPágina atual
sizeintegerQuantidade de registros por página
count_pagesintegerTotal de páginas encontradas
dataarrayArray de pagamentos encontrados

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"
}

Consultar pagamentos por cliente

Liste todos os pagamentos realizados para um cliente específico usando o número do documento.

Route

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

Headers

{
  "Authorization": "YOUR_API_KEY"
}

Query Parameters

ParâmetroTipoObrigatórioDescrição
document_numberstringSimNúmero do documento do beneficiário (CPF ou CNPJ)

Exemplo de requisição:

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

Resposta 200 - Sucesso:

{
  "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"
    },
    {
      "id": 686,
      "transaction_id": "12345678912",
      "name": "Daniel Menegasso",
      "document_number": "12345678900",
      "document_type": "CPF",
      "currency": "BRL",
      "amount": 150,
      "status": 1,
      "bank": {
        "type": "TED",
        "bank_code": "001",
        "account_agency": "1234",
        "account_number": "12345-5"
      },
      "created_at": "2021-12-02T10:15:20.000Z",
      "paid_at": "2021-12-02T11:16:33.000Z"
    }
  ],
  "total": 2
}

Campos da Resposta

ParâmetroTipoDescrição
dataarrayArray de pagamentos encontrados
totalintegerTotal de pagamentos encontrados para o cliente

Resposta 400 - Documento inválido:

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

Resposta 404 - Nenhum pagamento encontrado:

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

Status de Pagamentos

Os status de pagamentos são representados por números inteiros:

StatusDescrição
0Pagamento criado, aguardando processamento
1Pagamento aprovado/concluído
2Pagamento cancelado
3Pagamento rejeitado
4Pagamento em processamento

Diferenças entre PIX e TED

Resposta PIX

  • Contém o campo bank.ispb (8 dígitos)
  • Processamento rápido (segundos a minutos)
  • Campo paid_at geralmente próximo ao created_at

Resposta TED

  • Contém o campo bank.bank_code (3 dígitos)
  • Processamento mais lento (horas)
  • Campo paid_at pode ser significativamente diferente do created_at

Observações Importantes

  • IDs únicos: Tanto id quanto transaction_id são únicos e podem ser usados para consulta
  • Histórico completo: A consulta por cliente retorna todo o histórico de pagamentos
  • Webhook: É recomendado usar webhooks para receber atualizações automáticas de status
  • Cache: Os dados podem ter um pequeno delay (poucos segundos) após a criação

Consultar pagamentos por período em CSV

Liste pagamentos em um período específico em formato CSV, esta exportação contempla todos os pagamentos e todos os status, sem paginação.

Route

GET /v2/withdrawals/period/csv

Headers

{
  "Authorization": "YOUR_API_KEY"
}

Query Parameters

ParâmetroTipoObrigatórioDescrição
startstringSimData inicial do período (formato: "YYYY-MM-DD HH:MM:SS")
endstringSimData final do período (formato: "YYYY-MM-DD HH:MM:SS")

Exemplo de requisição:

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'

Resposta 200 - Sucesso:

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
...

Resposta 400 - Data inválida:

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

Status de Pagamentos

Os status de pagamentos são representados por números inteiros:

StatusDescrição
0Pagamento criado, aguardando processamento
1Pagamento aprovado/concluído
2Pagamento rejeitado
3Pagamento devolvido
Criar PagamentoComprovante PDF