How to Integrate an eSIM API Into Your Website or App

This guide walks through a typical eSIM API integration, using the Fully Signal API as the example. The same pattern applies to a website, a booking engine or a mobile app.

The architecture

Your customer never talks to the eSIM API directly. The flow is:

1. Your frontend shows destinations and plans.
2. Your customer pays you through your own checkout.
3. Your backend calls the eSIM API to create the order.
4. Your backend gives the customer the install link or QR code.
5. Webhooks keep your system updated afterwards.

Keep your API key on the server — never in a browser or mobile app bundle.

Step 1: Get a test key

Register for a free partner account, open the panel and create a test API key. It works against sample destinations and prices, and nothing is charged. See sandbox testing.

Step 2: Sync the catalogue

Fetch destinations and packages and store them in your database:

GET /api/v1/destinations
GET /api/v1/packages?destination=IT

Refresh periodically (for example every few hours) so prices and availability stay current. Store the package ID with each product you sell.

Step 3: Create the order after payment

When your payment succeeds, create the order from your backend:

POST /api/v1/orders
Authorization: Bearer fsk_test_…
Idempotency-Key: checkout-7f3a91
Content-Type: application/json

{ "package_id": "IT_5GB_30D_FIXED", "customer_ref": "booking-4821" }

• The Idempotency-Key makes retries safe: if your request times out and you send it again with the same key, you won't buy a second eSIM.
• customer_ref is your own reference, so you can match the order to your booking.

Step 4: Deliver the eSIM

The response contains the eSIM, including its ICCID and an install_page_url — a page with your branding, the QR code and step-by-step instructions for iPhone and Android. You can:

• Redirect the customer to it after checkout
• Email it in the confirmation
• Show the QR code inside your app

Step 5: Listen to webhooks

Register a webhook URL in the panel. Fully Signal sends events such as order.completed, order.failed, order.refunded, esim.activated and esim.expired, each signed with an HMAC-SHA256 signature in the X-FULLYSIGNAL-Signature header. Verify the signature, then update your records. See eSIM webhooks.

Step 6: Add top-ups and refunds

POST /api/v1/esims/{iccid}/topup
POST /api/v1/orders/{id}/refund

Top-ups add data to an existing eSIM — no new QR code needed. Refunds work for eSIMs that were never installed and used no data. Read top-ups explained and refund rules.

Step 7: Go live

• Make your first deposit to unlock live keys and the real catalogue
• Swap the test key for a live key in your server configuration
• Restrict the key with an IP allowlist and the narrowest scopes you need
• Turn on auto top-up or low-balance alerts so sales never stop

Integration checklist

FAQ

Do I need a developer to integrate an eSIM API?

For automated sales, yes — someone comfortable with a REST API and webhooks. Without a developer, you can still sell from the partner panel.

Which programming languages work?

Any language that can make HTTPS requests and parse JSON — Node.js, PHP, Python, Ruby, Java, Go or .NET.

Can I put the API key in my mobile app?

No. Keep it on your server and have your app call your backend. A key in an app can be extracted.

How do I avoid buying two eSIMs when a request times out?

Send an Idempotency-Key header with each order. Repeating the request with the same key returns the original order instead of creating a new one.