Skip to main content
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: 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.
A USD account needs none of this. payable is price plus fee, fxQuoteId is null, and you may buy without quoting at all.

​
eSIMs are not bill payments

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 — 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 — 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.