Refunds
A Refund returns part or all of a succeeded charge to the original payment method. The refund's charge field is the charge id (the same value as id on the charge object). Only a charge in status succeeded can be refunded; the remaining refundable amount is the charge amount minus refunds that have not failed. Refunds are routed through the processor the original charge was made on, even after a processor change.
POST
/v1/refundsRefund a Charge
Refund a charge in full or in part. Secret key. Honours the Idempotency-Key header.
Request body
| Field | Type | Required | Description |
|---|---|---|---|
| charge | string | required | The charge id to refund (the id from POST /v1/charges). Must belong to the key's account and mode. |
| amount | integer | optional | Cents to refund. Positive integer no larger than what is still refundable. Omit to refund everything that is left. |
| reason | string | optional | Free text, stored and echoed. |
| merchant_id | string | optional | Multi-business accounts only; must belong to the key's account. |
Response
| Field | Type | Description |
|---|---|---|
| id | string | Refund id (the processor's reversal id). |
| object | string | "refund". |
| amount | integer | Cents refunded by this call. |
| currency | string | Always "USD". |
| status | string | succeeded or pending (an ACH refund may stay pending until the bank settles it). The list endpoint can also report failed. |
| charge | string | The charge you sent. |
| reason | string | null | As sent. |
| created | string | ISO 8601. |
- HTTP 201. 400 missing_required_param (charge) · 400 invalid_param (amount not a positive integer) · 404 resource_missing (unknown charge) · 400 charge_not_refundable (charge is pending, failed or canceled) · 400 charge_already_refunded · 400 amount_too_large (message states the refundable remainder in cents) · 400 refund_failed (processor refused) · 400 refund_unsupported · 403 merchant_not_found / merchant_not_onboarded / processing_disabled · 409 / 422 idempotency conflicts.
- After a full refund the charge reports status canceled, refunded true and amount_refunded equal to amount; a partial refund leaves status succeeded.
- Emits refund.created.
curl -X POST https://api.hlhunt.org/v1/refunds \
-H "Authorization: Bearer sk_live_your_api_key" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: refund-order-1234" \
-d '{
"charge": "TRxxxxxxxxxxxxxxxxxx",
"amount": 1000,
"reason": "Customer requested refund"
}'GET
/v1/refundsList Refunds
Refunds for the key's business, newest first.
Parameters
| Field | Type | Required | Description |
|---|---|---|---|
| limit | integer (query) | optional | 1–100, default 25. |
| offset | integer (query) | optional | Rows to skip, default 0. |
Response
| Field | Type | Description |
|---|---|---|
| object | string | "list". |
| data | array | { id, object, amount, currency, status (succeeded | failed | pending), charge, reason, created }. |
| total | integer | Total refunds. |
| has_more | boolean | offset + limit < total. |
curl -X GET "https://api.hlhunt.org/v1/refunds?limit=10&offset=0" \
-H "Authorization: Bearer sk_live_your_api_key"Endpoints
POST
/v1/refundsGET
/v1/refundsRefund a Charge
curl -X POST https://api.hlhunt.org/v1/refunds \
-H "Authorization: Bearer sk_live_your_api_key" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: refund-order-1234" \
-d '{
"charge": "TRxxxxxxxxxxxxxxxxxx",
"amount": 1000,
"reason": "Customer requested refund"
}'List Refunds
curl -X GET "https://api.hlhunt.org/v1/refunds?limit=10&offset=0" \
-H "Authorization: Bearer sk_live_your_api_key"