API reference
Record refund
Record a refund you sent from your own wallet.
POST
/invoices/:invoiceId/refundsRecord a refund you already sent from your own wallet. BOSPay is non-custodial and never moves refund money: this keeps amountRefunded, events and the audit log right. Each transaction hash can be recorded once, and total refunds cannot exceed the amount received. Console admins can also record refunds.
- Permission
- write:invoices
- Auth
- api-key
- Idempotent
- Yes — send Idempotency-Key
- Language
- Node.js
| Field | In | Type | Required | Description |
|---|---|---|---|---|
| invoiceId | path | string | Yes | An invoice that received a payment (paid, manual_review, reverted, or expired/cancelled with funds). |
| amount | body | string | Yes | Token amount you sent back, as a decimal string, in the invoice's token. |
| txHash | body | string | Yes | Hash of your refund transaction. 409 state_conflict if it was already recorded. |
| reason | body | string | No | Up to 500 characters, shown in the audit log. |
const response = await fetch(`${process.env.BOSPAY_API_BASE}/invoices/inv_1048/refunds`, {
method: "POST",
headers: {
"Content-Type": "application/json",
"BOSPay-Version": "2026-09-23",
"X-API-Key": process.env.BOSPAY_API_KEY,
"Idempotency-Key": "order-1048-attempt-1",
},
body: JSON.stringify({
"amount": "2.10",
"txHash": "0x5c504ed432cb51138bcf09aa5e8a410dd4a1e204ef84bfed1be16dfba1b22060",
"reason": "Overpayment returned"
})
});
if (!response.ok) {
throw new Error(`BOSPay request failed: ${response.status}`);
}
const data = await response.json();Success
201
{
"id": "rf_7Xq2Lm9Pz4Ka1Bc8Dn3Ev5Rt",
"object": "refund",
"invoiceId": "inv_1048",
"amount": "2.1",
"tokenSymbol": "USDC",
"chain": "sepolia",
"txHash": "0x5c504ed432cb51138bcf09aa5e8a410dd4a1e204ef84bfed1be16dfba1b22060",
"reason": "Overpayment returned",
"recordedBy": "key_9f2c",
"createdAt": "2026-09-24T09:12:00.000Z"
}Validation error
400
{
"error": {
"type": "invalid_request_error",
"code": "validation_error",
"message": "A valid fiatAmount is required.",
"field": "fiatAmount",
"requestId": "req_3f0c9a1b2c4d5e6f7a8b9c0d"
}
}