> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sakawave.com/llms.txt
> Use this file to discover all available pages before exploring further.

# eSIM introduction

> Why the quote exists, how eSIMs differ from bill payments, and when this is the wrong service.

An eSIM looks like a bill payment: pick a product from a catalog, pay, receive value. The difference is where the value goes. A bill payment delivers to an account number. An eSIM delivers to **a specific handset**, and only after someone physically installs it.

That gap — between paying and installing — is what the design is arranged around.

## Why the quote exists

The catalog is USD. Your account may not be.

Without a quote you would have three bad options: show the customer a USD price and surprise them on their statement, convert it yourself and disagree with what we charge, or refuse anyone who does not hold dollars.

The quote is the answer to all three:

| It returns | It prevents |
| - | - |
| `payable` in your account's currency | Showing a figure that is not the figure charged |
| `rate` and `expiresAt` | A rate that moved between the screen and the charge |
| `fxQuoteId` | Two orders quietly sharing one held rate |

Hold it for as long as the customer needs to read the screen, and no longer. It is a snapshot, and a snapshot from ten minutes ago is not a price.

<Note>
  A USD account needs none of this. `payable` is price plus fee, `fxQuoteId` is null, and you may buy without quoting at all.
</Note>

## eSIMs are not bill payments

| | Bill payment | eSIM |
| - | - | - |
| Pre-check | Enquiry, 10 minutes | Quote, \~2 minutes — and only for non-USD |
| Currency | NGN only | **Priced USD, payable in any currency you hold** |
| Amounts | Decimals, `"5000.00"` | **Minor units, `"999"`, with a rendered `display`** |
| Delivery | Immediate value | **Asynchronous — `provisioning` first** |
| Success state | `confirmed` | **`completed`** |
| After delivery | Nothing to manage | A profile with a life: usage, top-up, pause, revoke |

The bolded rows are where integrations go wrong. In particular: **do not treat a `provisioning` response as a failure.** It is the normal answer, and the eSIM usually exists a few seconds later.

## Money comes back on its own

A failed order refunds itself. So does an order the network only partly filled, and so does a `ready` eSIM you cancel before anyone uses it.

Every one of those returns **exactly what was debited, in the currency it was debited in** — never a fresh conversion. If a customer paid ₦15,684.30, they get ₦15,684.30 back, whatever the rate has done since. The rate risk over those few minutes is ours, not theirs.

## Delivery is asynchronous, and that is not optional

The network allocates profiles on its own schedule. You have two ways to find out, and should use the first:

* **`esim.order.completed`** — arrives within seconds and carries the install details.
* **Poll [the order](/api-reference/esim/get-an-esim-order)** — while `status` is `provisioning`. A few seconds apart is plenty.

Sakawave also reconciles in the background, so an order is never lost because a webhook was missed. What you should not do is block a checkout on the eSIM existing: design the "preparing" state instead.

## When this is the wrong service

* **Data for a phone at home.** That is a [bill payment](/services/bill-payments/overview) — airtime and data bundles on a local network.
* **Calls or a phone number.** eSIMs here are data-only; the traveller keeps their own number on their own SIM for calls.
* **A device without eSIM support.** Most handsets sold since 2019 have it; nothing in the API can tell you whether a particular one does. Check before you sell.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.