A refund API request starts a reviewable billing workflow against an eligible settled transaction. It does not itself prove approval, a wallet credit or money returned through an external payment gateway. Keep the refund decision separate from the domain's lifecycle status.
IN THIS ARTICLE
01 Prepare the settlement evidence
| Method | Resource | Scope | Idempotency-Key |
|---|---|---|---|
GET |
/v2/refunds |
wallet:read |
Not required by this route |
POST |
/v2/refunds |
refunds:write |
Required |
- Find the original order and settlement owned by the authenticated account.
- Confirm the original payer, currency, settled amount and any previous refunds.
- Choose an amount within the remaining refundable settlement and a supported method:
wallet_credit,invoice_refundormanual. - Submit
settlement_id, decimalamountand a useful reason, with the required HTTP idempotency header. - Save the returned refund ID and follow its recorded state in the refund collection and related billing evidence.
An illustrative body is:
{
"settlement_id": "OWNED_SETTLEMENT_ID",
"amount": "10.00",
"method": "wallet_credit",
"reason_code": "customer_request",
"reason_detail": "Review against the original order and settlement."
}
The amount is an example, not a refund entitlement or current price. Use the actual remaining eligible amount and applicable service terms.
Is the body idempotency_key enough?
No. The optional refund workflow reference in the JSON body does not replace the route's required Idempotency-Key HTTP header. Retain the original request identity for an identical retry.
Does a refund cancel the domain?
No. A billing adjustment and a registry action are separate. A refund request should never be used as evidence that a domain was deleted, released or transferred away.
If the external payment status is unclear, reconcile the original settlement and gateway evidence before issuing another request. Do not alter wallet ledger rows or manually mark a gateway payment complete to clear a discrepancy. Provide authorised billing support with the settlement, order and refund references so it can review the actual remaining balance and decision.
Related articles
- Reconcile wallet balances, ledger entries and reserved holds
- Track domain orders and cancel only work that remains cancellable
- Retry Domain Nexus requests without creating duplicate domain operations
- What happens when my domain reseller purchase balance is low?
- Request DNSSEC changes and verify the parent DS separately