Cash-in routes

Nesta sessão você encontrará todos os endpoints necessários para criar, consultar, cancelar e gerenciar cobranças PIX utilizando a API PixToPay.

Endpoints Disponíveis

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

Criar cobrança PIX com expiração

Route

POST /v2/pix

Headers

{
  "Authorization": "YOUR_API_KEY",
  "Content-Type": "application/json", // opcional, padrão é application/json
  ...
}

Body

Parâmetro	Tipo	Obrigatório	Descrição
`transaction_id`	string	Sim	Identificador único da transação na sua plataforma (UUID v4 recomendado)
`currency`	string	Sim	Moeda da transação (apenas "BRL" é suportado)
`amount`	number	Sim	Valor da cobrança em reais (ex: 150.75)
`due`	string (ISO 8601)	Sim	Data e hora de expiração da cobrança (ex: "2024-12-31T23:59:59") enviar sempre no timezone UTC-0
`name`	string	Sim	Nome completo do pagador
`document_type`	string	Sim	Tipo de documento do pagador ("CPF" ou "CNPJ")
`document_number`	string	Sim	Número do documento do pagador (apenas números)
`webhook`	string	Sim	URL para receber notificações de status da cobrança via webhook
`phone_number`	string	Não	Número de telefone do pagador no formato internacional (ex: "5547999999999")
`email`	string	Não	Endereço de email do pagador
`external_id`	string	Não	Identificador externo para agrupar cobranças ou identificar usuário (ex: "group_1" ou "user_12345")

Exemplo de requisição:

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": "08965726921",
    "webhook": "https://webhook.site/1729bf83-5b8e-46fe-b125-1ef5932f4fef",
    "phone_number": "5547999999999",
    "email": "sandbox@pixtopay.com.br",
    "external_id": "group_1",
    "base64image": true
}'

Modelo de resposta [2xx]

Parâmetro	Tipo	Descrição
`id`	integer	Identificador único da cobrança PIX gerada
`transaction_id`	string	Identificador único da transação na sua plataforma
`status`	integer	Status atual da cobrança PIX (ver tabela de status abaixo)
`currency`	string	Moeda da transação (sempre "BRL")
`amount`	number	Valor da cobrança em reais
`due`	string (ISO 8601)	Data e hora de expiração da cobrança
`qrcode`	string	Código QR da cobrança PIX para pagamento
`qrcode_image`	string	(Opcional) Imagem do código QR em formato base64 (presente apenas se `base64image` for `true` no body)

Modelo de respostas [4xx]

Parâmetro	Tipo	Descrição
`type`	string	Tipo do erro ocorrido
`message`	string	Mensagem detalhando o erro ocorrido

Modelos de respostas [5xx]

Parâmetro	Tipo	Descrição
`message`	string	Mensagem detalhando o erro ocorrido

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

Resposta `200` com `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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"
}

Resposta `400` transaction_id duplicado:

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

Resposta `400` expiração inválida:

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

Resposta `5xx` erro interno:

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

Lista de status de cobranças PIX

Os status de cobranças PIX são representados por números inteiros. A baixo estão os possíveis status de uma cobrança PIX:

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

Fluxo de status

O fluxo de status de uma cobrança PIX segue a sequência abaixo:

0 (Criada) → 1 (Paga)
0 (Criada) → 2 (Cancelada)
0 (Criada) → 3 (Expirada)
0 (Criada) → 4 (Devolvida)*
0 (Criada) → 1 (Paga) → 4 (Devolvida)

*Obs: no caso da troca de status 0 (criada) diretamente para 4: (devolvida), isso ocorre quando o pagador realiza o pagamento, mas o valor é devolvido por algum motivo (ex: tentativa de pagamento por terceiros, lista restritiva, etc).

Cash-In Consultar Cobrança