Refunds

Blockchain transfers can't be reversed. 0fra solves refunds the same way Stripe handles disputes on cards that have already settled: by maintaining a reserve balance for each merchant and drawing from it.

Mental model

Order paid:
  reserve += merchantNet * reserve_bps / 10_000

Refund:
  if reserve >= refundAmount:
    reserve -= refundAmount
    state = "completed"
  else:
    platform absorbs the gap (negative balance)
    state = "completed"

The merchant's future payments will reduce the negative balance until they're square. You can configure a hard floor at the platform level — 0fra will block additional payments if a merchant goes too far negative.

Create a refund

curl -X POST https://api.0fra.dev/v1/refunds \
  -H "Authorization: Bearer sk_live_..." \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "order_id": "...",
    "amount": "20.00",
    "reason": "customer_request"
  }'

{
  "id": "...",
  "order_id": "...",
  "amount": "20.00",
  "source": "reserve",      // or "platform_absorb"
  "state": "completed"
}

Partial vs full refunds

You can issue multiple partial refunds against one order:

• Each call reduces a running tally on the order
• Once the tally equals the merchantGross, the order moves to refunded
• Otherwise it sits in partially_refunded

The total of all refunds cannot exceed the merchant's share of the original payment. 0fra's service fee and your platform fee are not refundable from this endpoint.

Listing refunds

GET /v1/refunds

Returns up to 100 most recent refunds across all your orders.

Webhooks

You'll receive refund.completed immediately. The payload includes the refund object plus order summary.

What's not on the roadmap

• On-chain refunds that pull from the merchant's wallet directly — the merchant would need to pre-approve a refund allowance, which adds significant UX complexity. Reserve-based is simpler and matches how every traditional rail works.
• Disputes / chargebacks — there's no card network here. Refund + customer-service workflow is your call.