Pay-In Refund
Check the status of a pay-in refund (both legs) or see a charge's refund
Pay-In Refund Status
Status of a Pay-In refund — the refund of a Pix charge you received (not a Pay-Out refund). A refund has two legs (BRL back to the payer, USDT recovered from your refund wallet). This endpoint returns both legs in a single per‑currency status object.
You can query it two ways:
- By refund id —
target=refund_id,id=<rpir_… or rpi_…>. Returns a single refund object. - From a charge — when you query a charge's status, if it has refunds the response
dataincludes arefundsarray (one entry per refund — a charge can have several partial refunds), ordered most‑recent first. Each entry has the same shape as a single refund.
Path Parameters
| Name | Type | Description |
|---|---|---|
| target | string | Required. refund_id |
| id | string | Required. The refund id — either pay_in_refund_request_id (rpir_…, returned by the refund endpoint) or kamipay_refund_id (rpi_…). |
Example Request
const target = "refund_id"
const id = "rpir_9e7f2fc2c0b14a8d9a1e3f5b7c2d4e6a"
const url = `${baseURL}/v2/status/tx_status?target=${target}&id=${id}`
const response = await fetch(url, {
method: "GET",
headers: {
Authorization: `Bearer ${access_token}`,
"Content-Type": "application/json",
},
});import requests
target = "refund_id"
id = "rpir_9e7f2fc2c0b14a8d9a1e3f5b7c2d4e6a"
url = f"{base_url}/v2/status/tx_status?target={target}&id={id}"
headers = {
'Authorization': f'Bearer {access_token}',
'Content-Type': 'application/json',
}
response = requests.get(url, headers=headers)Response
The refund object reports both legs under status, keyed by currency:
{
"status": "ok",
"msg": "Request ok",
"data": {
"kamipay_refund_id": "rpi_05bfc6100fd550be8a9a0c07",
"kamipay_id": "dqr_01kr3m9q5h7w2v4n6b8s3d5e9p",
"operation_id": "ptxr_01kr3m9p7n2s4d8h6e5b3t7w1k",
"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"
}
}{
"status": "ok",
"msg": "Request ok",
"data": {
"status": "done",
"qr_type": "dynamic",
"kamipay_id": "dqr_01kr3m9q5h7w2v4n6b8s3d5e9p",
"operation_id": "ptxr_01kr3m9p7n2s4d8h6e5b3t7w1k",
"amount_brl": "5.05",
"amount_usdt": "1.800000",
"refunds": [
{
"kamipay_refund_id": "rpi_05bfc6100fd550be8a9a0c07",
"kamipay_id": "dqr_01kr3m9q5h7w2v4n6b8s3d5e9p",
"operation_id": "ptxr_01kr3m9p7n2s4d8h6e5b3t7w1k",
"status": {
"brl": { "status": "done", "amount": "3.00", "bank_txid": "E29384756202606051851aB7cD3xY9mZ" },
"usdt": { "status": "done", "amount": "1.069306", "tx_hash": "0xa3f9b2c1e7d4865094bd28fa1c3e6b85907df42a3b9c1de80f5a672bc41e9d3f" }
},
"original_bank_txid": "E10573521202606051851hovcb9HXqev",
"timestamp": "2026-06-05T19:10:44.882000+00:00"
},
{
"kamipay_refund_id": "rpi_91ab44e7c0d2f1336e8a2b5d",
"kamipay_id": "dqr_01kr3m9q5h7w2v4n6b8s3d5e9p",
"operation_id": "ptxr_01kr3m9p7n2s4d8h6e5b3t7w1k",
"status": {
"brl": { "status": "done", "amount": "2.05", "bank_txid": "E29384756202606051852cD4eF5gH6jK" },
"usdt": { "status": "done", "amount": "0.730694", "tx_hash": "0xb7c1de80f5a672bc41e9d3fa3f9b2c1e7d4865094bd28fa1c3e6b85907df42a3" }
},
"original_bank_txid": "E10573521202606051851hovcb9HXqev",
"timestamp": "2026-06-05T18:55:12.401000+00:00"
}
]
}
}The example shows a charge with two partial refunds. A charge with a single (full) refund still returns a one‑element refunds array.
Field reference
| Field | Description |
|---|---|
| kamipay_refund_id | Internal refund id (rpi_…). |
| operation_id | The original charge's PIX operation id (ptxr_…). |
| original_bank_txid | The end‑to‑end id of the original cash‑in being refunded. |
| status.brl | The BRL refund leg. |
| status.usdt | The USDT recovery leg. |
| status.*.status | created, processing, done, or failed. |
| status.brl.amount | BRL amount refunded. |
| status.brl.bank_txid | End‑to‑end id of the refund bank transfer (empty until sent). |
| status.usdt.amount | USDT amount recovered. |
| status.usdt.tx_hash | On‑chain hash of the recovery transfer (null until broadcast). |
The two legs progress independently: the BRL leg usually reaches done first; the USDT leg moves created → processing → done (or failed if the on‑chain recovery reverts). A refund is only fully complete when both legs are done.