Core APIs

Refunds API

Issue a refund on a paid session. Executes at the next settlement batch.

Endpoints

Method	Path	Purpose
POST	`/gateway/api/refunds/`	Issue a refund
GET	`/gateway/api/refunds/`	List all refunds
GET	`/gateway/api/refunds/<session_ref>/`	Retrieve a refund

Issue a refund

curl -X POST https://blockcade.app/gateway/api/refunds/ \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: refund-ref_abc123-001" \
  -d '{"session": "ref_abc123", "reason": "Customer changed mind"}'

Body fields

Field	Type	Required	Description
`session`	string	yes	Reference of the paid session (`ref_...`)
`reason`	string	no	Internal note, ≤ 280 chars

Response (201 Created — or 200 OK if already refunded)

{
  "id": "ref_ref_abc123",
  "object": "refund",
  "session": "ref_abc123",
  "amount": "99.00",
  "currency": "USD",
  "status": "pending",
  "refunded_at": "2026-08-08T14:30:00+00:00",
  "refunded_by": "api"
}

Idempotency: pass Idempotency-Key to safely retry. A repeat call with the same body returns the cached response.

Node.js SDK

const refund = await bc.refunds.issue('ref_abc123', {
  reason: 'Customer changed mind',
  idempotencyKey: 'refund-ref_abc123-001',
});
console.log(refund.status);  // 'pending' → 'processed' after settlement