Pay-In Refund
Receive notifications about refunds of your Pix charges (both legs)
When a Pay-In (a Pix charge you received) is refunded, kamiPay sends you webhooks so you can track the refund without polling. This is unrelated to Pay-Out refunds; pay-in refunds carry event: "payin_refund" and rpi_… ids. A refund has two legs (BRL back to the payer, USDT recovered from your refund wallet) and every webhook reports both legs in a per‑currency status object.
When you receive it
You get a refund webhook at each milestone:
- BRL refunded — the BRL was returned to the payer. At this point the USDT leg is still
created/processing. - USDT recovery resolved — the on‑chain recovery from your refund wallet finished:
donewhen mined, orfailedif it reverted.
Both webhooks carry the same shape; only the status object changes as each leg progresses. (There is no separate event name per leg — read the per‑currency status.)
Payload
{
"kamipay_refund_id": "rpi_05bfc6100fd550be8a9a0c07",
"kamipay_id": "dqr_01kr3m9q5h7w2v4n6b8s3d5e9p",
"operation_id": "ptxr_01kr3m9p7n2s4d8h6e5b3t7w1k",
"type": "charge",
"event": "payin_refund",
"status": {
"brl": {
"status": "done",
"amount": "5.05",
"bank_txid": "E29384756202606051851aB7cD3xY9mZ"
},
"usdt": {
"status": "done",
"amount": "1.800000",
"tx_hash": "0xa3f9b2c1e7d4865094bd28fa1c3e6b85907df42a3b9c1de80f5a672bc41e9d3f"
}
},
"original_bank_txid": "E10573521202606051851hovcb9HXqev",
"timestamp": "2026-06-05T18:55:12.401000+00:00"
}Fields
| Field | Description |
|---|---|
| event | Always payin_refund. |
| type | Always charge (a refund of a Pix charge you received). |
| operation_id | The original charge's PIX operation id (ptxr_…), as returned by create_dynamic_pix. |
| kamipay_refund_id | Internal refund id (rpi_…). |
| original_bank_txid | End‑to‑end id of the original cash‑in being refunded. |
| status.brl | BRL refund leg: status (created/processing/done/failed), amount (BRL), bank_txid (refund bank transfer e2e). |
| status.usdt | USDT recovery leg: status (created/processing/done/failed), amount (USDT), tx_hash (on‑chain recovery, null until broadcast). |
| timestamp | When the webhook was generated. |
Use operation_id to correlate the refund with the original charge in your system (it's the same id you received when creating the QR). A refund is fully complete only when both status.brl and status.usdt are done.
Always validate the webhook signature using the method described in the Introduction before processing any webhook events.