Pix recebido sem cobrança

Quando alguém manda um Pix direto para uma chave da conta, sem cobrança, o valor entra como depósito e chega o webhook DEPOSIT_RECEIVED. Use o depositId desse webhook nas rotas desta página.

Consultar

GET /transactions/deposit/{depositId}, escopo DEPOSIT_READ.

{
  "id": "cmu4a1b2c000001s6xyz98765",
  "method": "PIX",
  "amount": 5000,
  "serviceFee": 50,
  "netAmount": 4950,
  "e2e": "E99999999202610051433a1b2c3d4e5f",
  "receiverPixKey": "b3c7e9a2-4f1d-4c8a-9e2b-7d5f6a8c1e03",
  "payer": { "name": "João Pereira", "document": "***.456.789-**", "bankIspb": "99999999", "bankName": "Banco Exemplo S.A." },
  "paidAt": "2026-10-05T16:10:02.551Z",
  "createdAt": "2026-10-05T16:10:03.120Z",
  "refundedAmount": 0,
  "refundInProgressAmount": 0,
  "refundableAmount": 5000,
  "openInfractionProtocol": null,
  "refunds": []
}

• amount é o que o pagador mandou. netAmount é o que entrou na conta, já sem a tarifa (serviceFee).
• e2e é o end-to-end do Pix. receiverPixKey é a chave da sua conta que recebeu.
• payer é quem pagou, como o banco informou, com o CPF mascarado ou o CNPJ formatado.

O comprovante sai em GET /transactions/deposit/{depositId}/receipt, em PDF codificado em base64.

Devolver ao pagador

POST /transactions/deposit/{depositId}/refund, escopo REFUND. O dinheiro volta para quem mandou o Pix. Mande amount para devolver parte; sem amount, devolve tudo o que ainda resta.

{ "amount": 5000 }

• A tarifa de estorno é cobrada à parte, além do valor devolvido. Ela aparece em refund, nos limites.
• Uma devolução por vez em cada depósito. Enquanto uma ainda é processada, a próxima é recusada com REFUND_IN_FLIGHT.
• Com contestação MED aberta sobre o depósito, a devolução é recusada com REFUND_INFRACTION_OPEN.
• Sem saldo suficiente, a devolução é recusada. A API nunca devolve menos do que o pedido.
• A resposta 200 traz o depósito com a devolução em refunds. O resultado chega pelos webhooks REFUND_COMPLETED ou REFUND_FAILED, com depositId no lugar de paymentId. Até lá, o valor aparece em refundInProgressAmount; o que já foi devolvido fica em refundedAmount.
• A rota não aceita Idempotency-Key. Num 502, a devolução pode ter saído: consulte o depósito antes de pedir de novo.

Todas as recusas estão em Devolver depósito.

Devolução de um Pix enviado

Quando quem recebeu um saque devolve o valor, o crédito entra como depósito e pode ser consultado pelo depositId. Na maioria das vezes chega o webhook WITHDRAW_REFUND_RECEIVED, com o withdrawId do saque, sem tarifa e com a linha PAYOUT_REFUND_RECEIVED no extrato. Às vezes a devolução chega como Pix comum: webhook DEPOSIT_RECEIVED, com tarifa e linha DEPOSIT. Trate os dois casos.