Refunds
The refunds endpoints of the Kashu API, with their parameters, objects, errors and examples. The guide explains how they fit together.
The refund object
| Field | Type | About |
|---|
id | string | An id that starts rf_. |
object | string | Always "refund". |
amount | integer | In the currency's minor unit, such as cents for USD. More than 0. |
currency | string | Three capital letters, such as USD. |
payment | string | An id that starts py_. |
status | enum | One of pending, succeeded, failed. |
reason | enum or null | One of requested_by_customer, duplicate, fraudulent. |
failure_reason | enum or null | One of already_refunded, processing_error. |
metadata | map of strings | |
livemode | boolean | |
created | integer | Unix seconds. |
{
"id": "rf_1a2B3c4D5e6F7g8H9i0J1k2L",
"object": "refund",
"amount": 4999,
"currency": "USD",
"payment": "py_1a2B3c4D5e6F7g8H9i0J1k2L",
"status": "succeeded",
"reason": null,
"failure_reason": null,
"metadata": {
"order": "1001"
},
"livemode": false,
"created": 1762473600
}
POST /v1/refunds
Refund part or all of a captured payment. Without an amount, all that is left.
- Scope
refunds:write- Keys
- Secret, or restricted with the scope below.
- Idempotency-Key
- Required. This endpoint moves money. See Idempotency.
Parameters
| Name | In | Type | Required | About |
|---|
Idempotency-Key | header | string | Required | Required. Retry with the same key and get the same result. Up to 255 characters. |
Kashu-Version | header | string | Optional | The API version to answer in. Defaults to the key's pinned version. |
Request body
| Field | Type | Required | About |
|---|
payment | string | Required | An id that starts py_. |
amount | integer | Optional | In the currency's minor unit, such as cents for USD. More than 0. Up to 99999999. |
reason | enum | Optional | One of requested_by_customer, duplicate, fraudulent. |
metadata | map of strings | Optional | Keys up to 40 characters, values up to 500. |
Errors
| Status | Codes |
|---|
| 400 | invalid_json, parameter_missing, parameter_invalid, parameter_unknown, api_version_invalid, idempotency_key_missing, idempotency_key_invalid, idempotency_key_reused, payment_unexpected_state, amount_too_large |
| 401 | api_key_missing, api_key_invalid, api_key_expired |
| 403 | livemode_unavailable, insufficient_scope, publishable_key_not_allowed, payments_not_enabled |
| 404 | resource_missing |
| 409 | idempotency_key_in_use, operation_in_progress |
| 429 | rate_limited |
| 500 | api_error |
Examples
curl https://api.kashupay.com/v1/refunds \
-H "Authorization: Bearer $KASHU_SECRET_KEY" \
-H "Idempotency-Key: refunds-create-1001" \
-H "Content-Type: application/json" \
-d '{"payment":"py_1a2B3c4D5e6F7g8H9i0J1k2L","amount":4999}'
const refund = await kashu("POST", "/v1/refunds", {
"payment": "py_1a2B3c4D5e6F7g8H9i0J1k2L",
"amount": 4999
}, { idempotencyKey: "refunds-create-1001" });
console.log(refund.status);
GET /v1/refunds
List refunds, newest first.
- Scope
refunds:read- Keys
- Secret, or restricted with the scope below.
- Idempotency-Key
- Not used. A read changes nothing.
Parameters
| Name | In | Type | Required | About |
|---|
payment | query | string | Optional | An id that starts py_. |
limit | query | integer | Optional | At least 1. Up to 100. Defaults to 10. |
cursor | query | string | Optional | |
Kashu-Version | header | string | Optional | The API version to answer in. Defaults to the key's pinned version. |
Errors
Examples
curl "https://api.kashupay.com/v1/refunds?limit=3" \
-H "Authorization: Bearer $KASHU_SECRET_KEY"
const list = await kashu("GET", "/v1/refunds?limit=3");
console.log(list.has_more);
GET /v1/refunds/{id}
Retrieve a refund.
- Scope
refunds:read- Keys
- Secret, or restricted with the scope below.
- Idempotency-Key
- Not used. A read changes nothing.
Parameters
| Name | In | Type | Required | About |
|---|
id | path | string | Required | An id that starts rf_. |
Kashu-Version | header | string | Optional | The API version to answer in. Defaults to the key's pinned version. |
Errors
Examples
curl https://api.kashupay.com/v1/refunds/rf_1a2B3c4D5e6F7g8H9i0J1k2L \
-H "Authorization: Bearer $KASHU_SECRET_KEY"
const refund = await kashu("GET", "/v1/refunds/rf_1a2B3c4D5e6F7g8H9i0J1k2L");
console.log(refund.status);