Request a refund

POST /v1/refund-requests — requires refund_requests:write and an Idempotency-Key.

curl -X POST https://<your-orion-host>/v1/refund-requests \
  -H "Authorization: Bearer $ORION_KEY" \
  -H "Idempotency-Key: refund-NW-1042-1" \
  -H "Content-Type: application/json" \
  -d '{ "payment_id": "pay_7k2m4n6p8q0r2s4t6v8w", "amount": 5000, "reason": "Customer returned one item" }'

{ "id": "rr_3f…", "object": "refund_request", "payment_id": "pay_7k2…", "amount": 5000, "currency": "CAD", "status": "requested", "reason": "Customer returned one item", "created_at": "…" }

• Only succeeded payments can be refunded.
• The total of active refunds cannot exceed the payment amount (refund_exceeds_available).
• Repeating a request with the same idempotency key returns the original refund with 200 and Idempotent-Replayed: true.
• Refunds are authorized before submission to the provider. Listen for refund.completed / refund.failed.
• For USDC payments, include crypto_refund_destination_note describing how the customer's own destination is verified. Orion does not refund to the sending address automatically.