Request a refund

POST/v1/esims/{iccid}/refund-requestesims:write

Refunds are not self-service. This endpoint opens a request that eSIMfo reviews. When approved, the amount you paid for the eSIM is credited back to your balance and the eSIM becomes REFUNDED. When rejected, you get the reason.

Unused lines are normally refunded in full. Lines that were installed or that used data are reviewed case by case — say what happened in notes.

Path parameters

Name	Notes
`iccid`	The ICCID of the eSIM

Request

Field	Type	Required	Notes
`reason`	string	Yes	One of the reason codes below
`notes`	string	When `reason` is `OTHERS`	Up to 1000 characters. Shown to the reviewer and passed on to the network

Reason codes: INSTALLATION_FAILURE, NO_COVERAGE, APN_FAILURE, TRIP_CANCELLATION, INTERMITTENT_CONNECTION, BLOCKED_NETWORK, CHANGE_OF_PLAN, DELETED_ESIM, EARLY_EXPIRY, HOTSPOT_NOT_WORKING, IMSI_CHANGE, INCOMPATIBLE_DEVICE, LOCKED_DEVICE, NO_VOICE_TEXT_SERVICES, OVERCHARGED, SLOW_SPEED, TOP_UP_PACKAGE_FAILURE, UNKNOWN_CHARGES, WRONG_PURCHASE, UNABLE_TO_ACCESS_APPS, SERVICE_DEGRADATION, QR_ISSUE_PARTNERS, OTHERS.

curl -X POST https://partner-api.esimfo.com/v1/esims/89852350326100409575/refund-request \
  -H 'Authorization: Bearer esf_live_at_...' \
  -H 'Content-Type: application/json' \
  -d '{
    "reason": "WRONG_PURCHASE",
    "notes": "Customer bought a Turkey package but is travelling to Greece"
  }'

Response `201`

{
  "id": "rfr_5e7a12c3",
  "esim_id": "esm_9a3f1c",
  "iccid": "89852350326100409575",
  "status": "PENDING",
  "reason": "WRONG_PURCHASE",
  "notes": "Customer bought a Turkey package but is travelling to Greece",
  "review_note": null,
  "refunded_amount": null,
  "currency": "EUR",
  "created_at": "2026-08-22T10:12:44.000Z",
  "reviewed_at": null
}

Field	Notes
`status`	`PENDING` until reviewed, then `APPROVED` or `REJECTED`. `CANCELLED` if withdrawn from the portal
`review_note`	What the reviewer told you — the rejection reason, or a note on approval
`refunded_amount`	Credited to your balance once approved; `null` otherwise

Following the outcome

Subscribe to refund_request.approved and refund_request.rejected in Webhooks, or poll Get a refund request. An approved request also raises order.refunded for the refunded eSIM.

Notes

One pending request per eSIM. A second call while one is waiting returns 409 pending_request_exists.
An eSIM that is already REFUNDED returns 409 conflict.
A pending request can be withdrawn with Cancel a refund request.

Errors

Status	Code	Cause
404	`not_found`	No such ICCID, or it belongs to another account
409	`pending_request_exists`	A request for this eSIM is already waiting for review
409	`conflict`	The eSIM was already refunded
422	`validation_failed`	Unknown reason code, or `OTHERS` without `notes`
403	`insufficient_scope`	Key lacks `esims:write`