Skip to main content
POST
Request a refund
Asks us to refund one eSIM. We check with the network before deciding, so the answer is not in this response: it arrives later on your webhook as esim.refunded or esim.refund_declined. The response says where the request stands now. Only an eSIM that has been issued to you can be refunded, and in practice only one that was never installed. Check refundable on Get eSIM status first.

Asking again

Safe to repeat:
  • An open request (requested) comes back as it is.
  • A settled one (refunded) comes back as it is.
  • A declined one is opened again, with the reason and note you send this time.

Authorizations

X-Esimmu-Access-Key
string
header
required

Your partner access key. Identifies you on every request.

X-Esimmu-Signature
string
header
required

Lowercase hex HMAC-SHA256 over the five-line string {METHOD}\n{REQUEST_PATH}\n{TIMESTAMP}\n{ACCESS_KEY}\n{BODY_SHA256}, keyed with your Base64-decoded secret key.

REQUEST_PATH includes the /api prefix and excludes the domain and any query string. BODY_SHA256 is the lowercase hex SHA-256 of the exact body bytes you send; for a request with no body, hash the empty string. The string always has five lines.

X-Esimmu-Timestamp
string
header
required

Unix seconds (UTC), within 5 minutes of our clock.

Path Parameters

topup_id
string
required

The eSIM, as returned by Create an order and sent in esim.issued.

Body

application/json
reason
string

Why you are asking, in your own words or as a short code.

note
string

Anything that helps us check with the network.

Response

Where the refund request stands now.

topup_id
string
status
enum<string>
Available options:
requested,
refunded,
declined
requested_at
string<date-time> | null
refunded_at
string<date-time> | null
declined_at
string<date-time> | null
decline_reason
string | null
Last modified on November 16, 2026