Devolver cobrança PIX

Nesta seção, você aprenderá como devolver (reembolsar) cobranças PIX que foram pagas.

Endpoints Disponíveis

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

Devolver cobrança

Realiza a devolução (reembolso) de uma cobrança PIX que foi paga. A devolução é processada e o valor é estornado ao pagador.

Route

POST /v2/pix/refund

Headers

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

Body 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/pix/refund' \
--header 'Authorization: API_KEY' \
--header 'Content-Type: application/json' \
--data '{
    "id": 59276
}'

Resposta `200` - Sucesso:

{
  "id": 59276,
  "transaction_id": "12345678933",
  "status": 4,
  "currency": "BRL",
  "amount": 145,
  "refund_status": "processing"
}

Campos da Resposta

Parâmetro	Tipo	Descrição
`id`	integer	ID interno da cobrança
`transaction_id`	string	Identificador único da transação na sua plataforma
`status`	integer	Status da cobrança (será 4 para devolvida)
`currency`	string	Moeda da transação
`amount`	number	Valor devolvido
`refund_status`	string	Status do processo de devolução

Resposta `400` - Cobrança não encontrada:

{
  "type": "ValidationError",
  "message": "Charge not found"
}

Resposta `400` - Cobrança não paga:

{
  "type": "ValidationError",
  "message": "Charge must be paid to be refunded"
}

Resposta `400` - Cobrança já devolvida:

{
  "type": "ValidationError",
  "message": "Charge already refunded"
}

Observações Importantes

Somente cobranças pagas podem ser devolvidas: A cobrança deve estar com status 1 (paga) para ser devolvida
Devolução é irreversível: Uma vez solicitada a devolução, não é possível cancelar o processo
Webhook: Quando a devolução for concluída, um webhook será enviado com o status atualizado para 4 (devolvida)
Prazo: O prazo para devolução pode variar de acordo com o banco receptor

Fluxo de Status

Ao devolver uma cobrança, o status muda de:

1 (Paga) → 4 (Devolvida)

Webhook de Devolução

Quando a devolução for processada, você receberá um webhook no endpoint configurado com os seguintes dados:

{
  "id": 59276,
  "transaction_id": "12345678933",
  "status": 4,
  "event": "refund_completed",
  "amount": 145,
  "refunded_at": "2024-12-02T10:30:00.000Z"
}

Consultar Cobrança Cash-Out