Guides

Refunds

Recorded and reviewed, not automatic yet

Today a refund request is recorded and reviewed by ClearGateway staff. Sending the money back on-chain is not automated yet. You will see the status change as staff approve or reject it.

Request a refund

Refund a succeeded (or partially refunded) payment. Leave amount out to refund everything that has not been refunded yet. to_address is the wallet the money should go to. Check it carefully: on-chain refunds cannot be undone.

curl https://cleargateway-api.onrender.com/v1/refunds \
  -H "Authorization: Bearer $CLEARGATEWAY_API_KEY" \
  -H "Idempotency-Key: refund-order-1042-1" \
  -H "Content-Type: application/json" \
  -d '{
    "payment_intent_id": "pi_...",
    "amount": "5000000",
    "to_address": "0xCustomerWalletAddress...",
    "reason": "customer_request"
  }'

Rules

  • The payment must be succeeded or partially_refunded; otherwise the request is refused.
  • The total of your open and approved refunds cannot exceed the amount the customer paid (the gross amount). A rejected refund frees its amount for a new request.
  • You cannot refund to ClearGateway's own contract addresses, the USDC contract or the zero address.
  • An Idempotency-Key is required, so retries never create two refunds.

Statuses

  • requested: waiting for review.
  • approved or rejected: the staff decision.
  • processing, succeeded, failed: reserved for when on-chain refunds are automated.

You receive a refund.created webhook when a request is recorded. List and fetch refunds with GET /v1/refunds and GET /v1/refunds/{id}, or use the dashboard's Refunds page.