Refunds

Overview

Refunds reverse a captured charge, in full or partially. A charge can receive multiple partial refunds as long as the total does not exceed the original amount.

Voiding a charge that has been authorized but not yet captured prevents it from settling — no refund is needed.

Create a refund

POST /v1/charges/:charge_id/refunds
Authorization: Bearer sk_test_...
Content-Type: application/json

{
  "amount": 2500,
  "reason": "customer_request"
}

Omit amount (or set it to the full charge amount) to issue a full refund.

Refund reasons

Response

{
  "id": "b1c2d3e4-...",
  "charge_id": "a1b2c3d4-...",
  "merchant_id": "...",
  "amount": 2500,
  "status": "succeeded",
  "reason": "customer_request",
  "provider_refund_id": "re_3O...",
  "created_at": "2024-01-15T11:00:00.000Z",
  "updated_at": "2024-01-15T11:00:01.000Z"
}

Retrieve a refund

GET /v1/refunds/:id
Authorization: Bearer sk_test_...

List refunds for a charge

GET /v1/charges/:charge_id/refunds
Authorization: Bearer sk_test_...

Void a charge

Voiding cancels an authorized charge before it settles. Only applicable to charges with status authorized.

POST /v1/charges/:id/void
Authorization: Bearer sk_test_...

Returns the full updated charge object with "status": "voided".

Rules

• Only captured charges can be refunded.
• Only authorized charges can be voided.
• Partial refunds accumulate — the sum cannot exceed the original amount.
• A fully refunded charge moves to status refunded. Partial refunds leave it as captured until fully refunded.
• Attempting an invalid transition returns 422 Unprocessable Content.