Refunds

You can only refund a collection whose status is completed. The refundable balance is the collection net amount (the captured amount minus fees), less any refunds already outstanding against it. Partial refunds accumulate: several partial refunds against one collection are allowed, and their sum can never exceed that net. The cap is enforced in the database with a row lock on the collection, so concurrent partial refunds can never race past it.

Every refund posts through the ledger. A reserve journal (rf:{id}:reserve) holds the funds when the refund is created; a settle journal (rf:{id}:settle) or a reverse journal (rf:{id}:reverse) closes it out when the refund completes or is released. If the reserve cannot be covered by your available balance, the refund fails with insufficient_balance and no money moves.

Amounts are decimal strings in the collection currency, which the refund always inherits: you never send a currency field. Zero-decimal currencies such as XAF and XOF are whole numbers, so 3,000 XAF is "3000", never "3000.00" and never 300000.

This resource is create-and-read only: there is a create endpoint and a retrieve-by-id endpoint, and no list endpoint. Track your refunds by the ids you receive, or watch the refund.completed and refund.failed events.

Reserve and dispatch a refund against a completed collection. The reserve is taken immediately, before any provider call.

In the sandbox the refund runs end to end against the payment simulator and resolves on its own. In production, refund provider adapters are still rolling out: a live refund currently reserves, then declines with provider_unavailable and releases the reserve.

Headers

• Authorization: Bearer sk_... - Your secret key. The refunds:write scope is required.
• Idempotency-Key - Required on this money-moving call. A unique key (1 to 255 characters) that makes the request safe to retry: resending the same key with the same body replays the original response instead of creating a second refund.
• Content-Type: application/json - The request body is JSON.

Request body

Example request

curl -X POST https://api.capayglobal.com/v1/refunds \
  -H "Authorization: Bearer sk_test_8fK2q0Zr41Xa" \
  -H "Idempotency-Key: 6f1a9c2e-4b7d-4a1e-9c33-2d5f8a0b1c2e" \
  -H "Content-Type: application/json" \
  -d '{
    "collection_id": "col_7pQ2r9Xm4KdA",
    "amount": "3000",
    "reason": "Customer returned item"
  }'

Example response

{
  "status": "success",
  "data": {
    "id": "rf_3mB8t1Yq5Le0",
    "object": "refund",
    "collection": "col_7pQ2r9Xm4KdA",
    "status": "processing",
    "amount": "3000",
    "currency": "XAF",
    "reason": "Customer returned item",
    "reason_code": null,
    "rail": "provider",
    "provider": "pawapay",
    "payout": null,
    "expected_resolution_at": "2026-08-29T12:49:56.000Z",
    "livemode": false,
    "created_at": "2026-08-29T12:34:56.000Z",
    "completed_at": null
  },
  "request_id": "b1e2c3d4-5f60-4a71-8b92-c0d1e2f3a4b5"
}

Omit amount for a full refund of everything still refundable; pass amount for a partial refund. A refund whose amount exceeds the remaining refundable balance is rejected with validation_error, and the database over-refund guard is the final backstop.

The response is the refund object with a 201 status. A refund created in the sandbox returns status "processing" (or "pending" if the simulator dispatch is slow) and settles to "completed" shortly after; retrieve it to see the final state.

Fetch a single refund by its id.

Headers

• Authorization: Bearer sk_... - Your secret key. The refunds:read scope is required.

Path parameters

Example request

curl https://api.capayglobal.com/v1/refunds/rf_3mB8t1Yq5Le0 \
  -H "Authorization: Bearer sk_test_8fK2q0Zr41Xa"

Example response

{
  "status": "success",
  "data": {
    "id": "rf_3mB8t1Yq5Le0",
    "object": "refund",
    "collection": "col_7pQ2r9Xm4KdA",
    "status": "completed",
    "amount": "3000",
    "currency": "XAF",
    "reason": "Customer returned item",
    "reason_code": "refund_settled",
    "rail": "payout",
    "provider": "pawapay",
    "payout": "po_5rD0v3Ws7Ng2",
    "expected_resolution_at": null,
    "livemode": false,
    "created_at": "2026-08-29T12:34:56.000Z",
    "completed_at": "2026-08-29T12:35:11.000Z"
  },
  "request_id": "c2d3e4f5-6a71-4b82-9c03-d1e2f3a4b5c6"
}

Both endpoints return the same object.

A refund starts initiated, moves to processing (or pending while it waits on the provider, enqueued while a rail is down), and ends in one of the terminal states below. Every status below emits its own webhook event: refund.pending, refund.enqueued, refund.processing, refund.completed, refund.failed, refund.cancelled, refund.expired and refund.reversed.

• initiated - The refund intent exists and the reserve is being taken.
• pending - Awaiting the provider (or parked by a dispatch timeout for the reconciler).
• processing - Accepted and being processed.
• enqueued - Held with the reserve intact while the rail recovers; it dispatches automatically when it does.
• completed - Terminal. The refund settled back to the payer.
• failed - Terminal. The refund failed and the reserve was released.
• cancelled - Terminal. The refund was cancelled before settlement.
• expired - Terminal. The refund was not completed before it expired.
• reversed - Terminal. A settled refund was reversed.

Errors use the standard envelope: a machine-readable code, a human message, and a next_step. Every error carries the request_id to quote to support.