eSIM API Integration: Architecture, Workflows, Webhooks and Security

An eSIM API allows a business to sell and manage connectivity inside its own website, mobile application, booking flow, customer portal or enterprise system.

The customer may never see the upstream connectivity provider. They choose a plan, pay the brand they know, receive installation information and manage the service through one consistent experience.

The technical integration behind that journey is more complex than sending one request and receiving a QR code. Orders may complete asynchronously. Profiles have their own lifecycle. Package validity may start at purchase, installation or first network use. Usage records can arrive later. Webhooks may be delayed, duplicated or delivered out of order. A timeout does not prove that an order failed.

A reliable integration must therefore answer four questions:

1. Which system owns each piece of data?
2. Which operations are synchronous and which are asynchronous?
3. How does the integration recover from uncertainty and failure?
4. How are sensitive operations authenticated, authorised, monitored and reconciled?

This guide explains a practical architecture for businesses integrating a white-label SIM and eSIM service. The examples are provider-neutral and illustrative. They are not a specification of the current SIM24.biz API.

Key takeaways

• An eSIM commerce API normally connects business systems to a provider platform. It does not give an ordinary storefront direct access to the eUICC or SM-DP+.
• Define systems of record before development. The commerce platform, provider, payment service and CRM should not all claim authority over the same state.
• Treat order fulfilment and many lifecycle operations as asynchronous, even when they usually complete quickly.
• Use a stable client-generated reference and an idempotency strategy so a retry cannot create an unintended second order.
• A timed-out request has an unknown outcome until the client retrieves the resource or receives a verified event.
• Webhook consumers must verify authenticity, reject stale or invalid messages, store event identifiers and process duplicates safely.
• An HTTP success code confirms that a request was accepted or returned successfully. It does not necessarily prove that a profile was installed or mobile data is working.
• Separate order, profile, package, network and payment states. Collapsing them into one “active” flag makes support and reconciliation unreliable.
• Use least-privilege credentials, secure secret storage, controlled rotation, strong tenant isolation and detailed audit logs.
• A realistic sandbox, failure testing and finance reconciliation are go-live requirements, not optional improvements.

What does an eSIM API actually do?

The term “eSIM API” is used for several different interfaces.

Commerce and product API

This interface exposes products, prices, destinations, allowances, validity and commercial rules. A partner uses it to build a catalogue or select a product for an order.

Order and fulfilment API

This creates an order, reserves or allocates a profile and returns fulfilment information when available.

Profile lifecycle API

Depending on the service and provisioning architecture, it may expose profile allocation, download status, enablement information, replacement or other permitted lifecycle actions.

Connectivity management API

This can expose SIM state, package state, usage, balance, top-ups, suspension, reactivation, network information and alerts.

Partner administration API

A platform serving resellers or enterprise customers may provide account hierarchy, permissions, price lists, limits and reporting.

Remote SIM provisioning interfaces

GSMA specifications define interfaces and security procedures used by components such as the SM-DP+, Local Profile Assistant, eUICC, IoT Profile Assistant and eSIM IoT Remote Manager.

These are not the same as a public commerce API. A travel application usually calls its provider's business API. The provider platform then works with the relevant profile inventory and provisioning infrastructure through controlled systems.

This distinction matters. A successful order API response may mean that a profile was allocated and activation information is available. It does not prove that the customer's device has downloaded the profile, enabled it, registered with a network or used data.

A practical reference architecture

A typical API-led white-label service contains the following layers.

Why an integration service is useful

It is possible for a storefront to call a provider directly, but a dedicated backend or integration layer normally creates a safer boundary.

It can:

• keep provider credentials away from browsers and mobile applications;
• map the provider's data model into the brand's internal model;
• enforce business rules and limits;
• attach idempotency references;
• store request and response identifiers;
• receive and verify webhooks;
• queue work and retry safely;
• protect the customer experience from upstream changes;
• support more than one provider later;
• produce an audit trail for support and finance.

The integration service does not need to be a large independent platform. It can be a clearly separated module within an existing backend. What matters is that provider-specific logic does not leak into every customer-facing component.

Define the system of record for every entity

Distributed systems become unreliable when ownership is ambiguous.

For each important entity, define which system is authoritative and which systems hold synchronised copies.

Do not overwrite history with the latest state

Store both:

• the current materialised state used by the application; and
• an append-only history of important requests, responses, events and manual actions.

If an order changes from pending to fulfilled, the current record should show fulfilled. The audit history should still show when it was created, which API request initiated it, when the provider accepted it and which event confirmed fulfilment.

This distinction is essential when investigating duplicate charges, delayed fulfilment or a disputed support action.

Use a clear domain model

An eSIM integration should not treat “an eSIM” as one database row containing every state.

Useful entities commonly include:

Product

The commercial offer available for sale, such as a 10 GB regional plan valid for 30 days. It may include destination coverage, allowance, validity rules, supported services and wholesale price.

Order

The commercial request to acquire a product. An order has its own status, customer reference, price and payment relationship.

Profile

The downloadable mobile subscription associated with provisioning identifiers and lifecycle state. One profile can be linked to an order, but it is not the order itself.

SIM or eUICC relationship

For physical SIM or managed IoT use cases, the service may separately model the card, eUICC, EID, ICCID, device and assigned asset.

Package or entitlement

The allowance and validity that the customer can consume. A top-up may create a new entitlement without creating a new profile.

Usage

Consumption records or aggregated balances reported by the provider. Usage should include an observation or rating time, unit and source.

Lifecycle operation

A requested action such as suspend, reactivate, top up, replace or cancel. The request may be pending before it succeeds or fails.

Event

An immutable notification that something happened, identified independently from the resource to which it relates.

Separating these concepts prevents contradictions such as “the eSIM was refunded but is still active”. The refund belongs to a payment or order, while the profile and package require their own resulting actions and states.

The catalogue workflow

The first integration decision is how products enter the storefront.

Live catalogue retrieval

The customer channel or backend requests products from the provider when needed.

Advantages:

• current provider data;
• fewer synchronisation jobs;
• quick access to new products.

Risks:

• checkout depends on provider availability and latency;
• wholesale details may leak into customer-facing logic;
• product changes can affect a live storefront immediately;
• repeated calls can consume rate limits.

Synchronised local catalogue

The brand periodically imports provider products and publishes approved retail versions from its own database.

Advantages:

• faster and more controlled storefront;
• local titles, translations, pricing and merchandising;
• deliberate approval of provider changes;
• resilience when the provider catalogue is temporarily unavailable.

Risks:

• products and prices can become stale;
• synchronisation and change review are required;
• unavailable inventory may remain visible.

Recommended control pattern

Use a synchronised catalogue for presentation, but validate critical availability and current commercial conditions before creating the provider order.

Store:

• immutable provider product identifier;
• provider and local version or last-updated timestamp;
• wholesale currency and cost;
• retail product identifier;
• destinations and networks where supplied;
• allowance, validity and activation rule;
• service restrictions;
• sale status and reason for withdrawal.

Never use a translated product name as an API identifier.

The complete purchase and fulfilment workflow

A robust customer journey can be designed as a sequence of state transitions.

Step 1: Validate the product

Confirm that the selected product remains saleable, the destination and service rules match the order and the current cost does not violate a commercial guardrail.

Step 2: Create a local order

Generate your own order identifier before calling external systems. Store the customer, product, quoted retail price, currency, tax treatment and a snapshot of material product terms.

The product can change later. The historical order should still show what the customer bought.

Step 3: Authorise or collect payment

The correct sequence depends on the payment method and provider rules.

Common patterns include:

• authorise payment, create the provider order, then capture;
• collect payment, create the provider order, then refund automatically if fulfilment fails;
• reserve provider inventory, collect payment, then confirm fulfilment.

Each pattern creates a different failure case. Document what happens if payment succeeds but the provider request times out, or the provider fulfils an order after payment capture fails.

Step 4: Submit the provider order

Send a stable partner reference and an idempotency value where supported.

An illustrative request might look like this:

POST /v1/orders HTTP/1.1
Authorization: Bearer <access-token>
Content-Type: application/json
Idempotency-Key: 7f5089ca-68d4-4e0e-91c3-f44d74c21c6a

{
  "partner_order_reference": "WEB-20260914-18427",
  "product_id": "regional-eu-10gb-30d",
  "quantity": 1
}

An illustrative accepted response could be:

{
  "order_id": "ord_82h41",
  "partner_order_reference": "WEB-20260914-18427",
  "status": "processing",
  "created_at": "2026-09-14T13:05:28Z"
}

The request and field names above are examples only. Real integrations must follow the chosen provider's documentation.

Step 5: Resolve the asynchronous outcome

The provider may return fulfilment immediately or continue processing.

Your integration should be able to obtain the outcome through:

• a webhook;
• retrieval of the order resource;
• a status endpoint;
• a controlled reconciliation job.

Do not keep a customer browser request open indefinitely while several external systems complete work.

Step 6: Store fulfilment data securely

Store the provider order identifier, profile reference, permitted activation data and relevant commercial state. Limit access to activation information because uncontrolled disclosure may allow an unintended person to install the profile.

Step 7: Deliver the installation journey

The customer may receive:

• a QR code;
• an SM-DP+ address and activation code;
• an operating-system-supported activation link;
• instructions within a mobile application;
• another provider-supported activation method.

The QR code is not the eSIM profile. It normally represents information used by the device to start a secure provisioning process.

Step 8: Observe later lifecycle events

Where the provider and provisioning chain expose them, later states may include download, installation, enablement, first network registration, package activation, usage and expiry.

Do not claim visibility that the upstream systems do not provide. Some platforms may know that activation information was issued but not receive an immediate, authoritative device-installation state.

Design explicit state machines

A single status field called active is too vague for a production integration.

Example order states

• created
• payment_pending
• payment_authorised
• submitted
• processing
• fulfilled
• failed
• cancelled
• refunded
• manual_review

Example profile states

• unassigned
• allocated
• activation_data_issued
• downloaded
• enabled
• disabled
• deleted
• expired
• unknown

Example package states

• pending
• available
• active
• depleted
• expired
• cancelled

These are illustrative internal states. The provider may expose different terminology and may not expose every transition.

Preserve unknown as a real state

Distributed systems create uncertainty. If a request times out after submission, the correct state is not automatically failed. The provider may have received and completed it.

Mark the outcome as unknown or pending reconciliation. Retrieve the resource using the stable partner reference or idempotency key before attempting a replacement order.

Idempotency: preventing accidental duplicate orders

An operation is idempotent when repeating the same intended request does not create an additional business effect.

HTTP defines methods such as GET, PUT and DELETE as idempotent in their intended semantics. POST is not idempotent by default, but order creation often uses POST. A business-level idempotency mechanism is therefore important.

A safe order pattern

1. Generate a unique idempotency key for the intended purchase.
2. Persist it before sending the provider request.
3. Send the same key when retrying that same intended operation.
4. Never reuse it for a different product, customer or quantity.
5. Store the provider response associated with the key.
6. Query by partner reference after an uncertain response.

The provider should define:

• which endpoints support idempotency;
• how long keys are retained;
• whether request payloads are compared;
• which response is returned for a repeated key;
• behaviour when the first request is still processing;
• conflict behaviour when the same key is reused with different data.

Idempotency does not replace reconciliation

A client or provider defect can still create inconsistent records. Finance and operations should compare local orders, provider orders, allocated profiles, payments and invoices regularly.

Timeouts and retry strategy

Retries should depend on the operation and failure type.

Generally retryable conditions

• temporary network failure;
• connection reset;
• provider service unavailable;
• explicit rate limit with a usable retry indication;
• server error documented as transient.

Conditions that normally require correction or review

• invalid product identifier;
• failed authentication;
• insufficient permission;
• malformed request;
• account balance or credit-limit failure;
• incompatible resource state;
• business-rule rejection.

Use bounded exponential backoff with jitter

Increasing the delay between retries reduces the chance that many clients will overwhelm a recovering service simultaneously. Add random variation, or jitter, so every worker does not retry at the same moment.

Set:

• a maximum number of attempts;
• a maximum elapsed time;
• a dead-letter or manual-review path;
• alerts for sustained failure;
• separate policies for reads and state-changing operations.

Never retry an uncertain order-creation request with a new reference merely because the first HTTP response was not received.

Webhooks: events delivered by the provider

Webhooks allow the provider to notify the partner when an asynchronous event occurs.

Possible events include:

• order fulfilled or failed;
• profile allocated;
• activation information available;
• profile state changed;
• package activated, depleted or expired;
• usage threshold reached;
• SIM suspended or reactivated;
• top-up completed;
• product or price changed;
• incident or maintenance status changed.

A representative event envelope

{
  "event_id": "evt_01J7S6A8QK",
  "event_type": "order.fulfilled",
  "occurred_at": "2026-09-14T13:05:31Z",
  "resource": {
    "type": "order",
    "id": "ord_82h41"
  },
  "data": {
    "partner_order_reference": "WEB-20260914-18427",
    "status": "fulfilled"
  }
}

This example is not a SIM24.biz schema.

Authenticate the sender

A webhook endpoint exposed to the internet should not trust a request merely because it contains a plausible order identifier.

Common controls include:

• a signature calculated over the exact request body;
• a timestamp included in the signed material;
• a narrow acceptance window to reduce replay risk;
• constant-time signature comparison;
• secret rotation with a controlled overlap period;
• mutual TLS for higher-assurance cases where supported;
• network controls as an additional layer, not the only authentication method.

The provider documentation should define the canonical signing algorithm and encoding. Parsing and serialising JSON before verification can alter bytes and cause valid signatures to fail or insecure comparisons to succeed unexpectedly. Verify the raw received body according to the documented scheme.

Process webhooks asynchronously

A reliable consumer normally:

1. receives the request;
2. checks size and basic transport requirements;
3. verifies signature and timestamp;
4. stores the event and event identifier durably;
5. returns the documented success response promptly;
6. processes the business effect through an internal queue or worker;
7. records success, retry or manual intervention.

Do not perform slow fulfilment, email or CRM work before acknowledging the webhook. A slow response can cause the provider to retry and increase duplicates.

Expect duplicate delivery

At-least-once delivery is common in event systems. A provider retries because it cannot know whether the consumer stored an event before a connection failed.

Store event_id with a uniqueness constraint. Reprocessing the same event should not issue a second refund, send multiple fulfilment emails or apply the same top-up twice.

Expect events to arrive out of order

A delayed order.processing event may arrive after order.fulfilled.

Use:

• resource version numbers where provided;
• provider sequence numbers;
• event occurrence time with caution;
• allowed state-transition rules;
• retrieval of the current resource when an event conflicts with local state.

Do not blindly replace the current state with the last webhook received.

Treat a webhook as a notification, not always the complete truth

For sensitive actions, use the event to trigger retrieval of the current provider resource. This reduces the data carried in events and allows the integration to confirm current state through an authenticated API call.

Polling and reconciliation are still necessary

Webhooks improve responsiveness but should not be the only synchronisation mechanism.

Events can be missed because of:

• configuration mistakes;
• expired secrets or certificates;
• temporary receiver outages;
• provider delivery defects;
• event-retention limits;
• a deployment that rejects valid payloads.

A reconciliation process can periodically compare:

• local pending orders with provider order state;
• local profile references with allocated inventory;
• top-up requests with completed entitlements;
• package balances with usage records;
• refunds with provider cancellations;
• monthly internal totals with the provider invoice.

Reconciliation frequency should reflect business risk. An unfulfilled paid order may need attention within minutes, while invoice-level usage reconciliation may run daily or monthly.

Authentication and authorisation

API security starts with identifying the calling workload and restricting what it can do.

Keep credentials on trusted servers

Never embed a provider secret in:

• browser JavaScript;
• a public mobile application;
• a downloadable configuration file;
• source code committed to a repository;
• support screenshots or logs.

Customer channels should call the brand's backend, which then calls the provider using server-side credentials.

Prefer short-lived credentials where available

OAuth 2.0 client credentials or another suitable workload-identity mechanism can issue limited-lifetime access tokens. RFC 9700 provides current best practice for OAuth 2.0 security and deprecates insecure historical patterns.

If the provider uses static API keys, compensate with:

• secret-manager storage;
• strict environment separation;
• least-privilege permissions;
• regular rotation;
• monitoring for unusual use;
• immediate revocation procedures;
• prohibition on sharing one key among unrelated applications or partners.

Authentication is not authorisation

A valid credential should not automatically grant access to every tenant, profile or operation.

Controls should enforce:

• partner and tenant boundary;
• resource ownership;
• permitted product catalogue;
• allowed lifecycle actions;
• spending or volume limits;
• administrator role;
• production versus sandbox access.

The OWASP API Security Top 10 2023 highlights broken object-level authorisation, broken authentication, broken function-level authorisation and unrestricted access to sensitive business flows among the principal API risks.

Protect administrative operations more strongly

Operations such as credential creation, bulk suspension, price changes, refund approval and data export may need:

• multi-factor authentication;
• approval by a second person;
• step-up authentication;
• restricted source networks;
• detailed audit records;
• notification to security or finance teams.

Request, response and data security

Transport security

Use current TLS configurations and validate certificates correctly. Do not disable verification to solve a test-environment problem.

Input validation

Validate type, length, format, allowed values and business meaning. A valid JSON document can still request an impossible quantity, unauthorised product or unsafe export range.

Output minimisation

Return only the fields the caller needs. Avoid exposing upstream secrets, internal network identifiers, personal information or full activation data to unauthorised roles.

Logging without leakage

Logs should contain enough information for diagnosis, including:

• correlation identifier;
• partner order reference;
• provider request identifier;
• endpoint and outcome category;
• timing and retry count;
• relevant resource identifiers;
• actor or workload identity.

Redact or exclude:

• access tokens and API keys;
• webhook secrets and signatures;
• payment-card data;
• authentication material;
• unnecessary personal data;
• complete activation codes where not required for support.

Data protection

Determine which personal data the provider needs and why. For services subject to the GDPR, define controller and processor roles by activity, enter the required processing terms, list subprocessors, control international transfers and establish retention and deletion procedures.

An API integration should support data minimisation. If the provider can fulfil an eSIM order using a partner order reference, it may not need the customer's full marketing profile or unrelated booking details.

Protect sensitive business workflows

Many API attacks do not exploit a malformed packet. They automate a valid function at abusive scale.

Examples include:

• creating large numbers of profiles using stolen payment methods;
• repeatedly requesting replacement activation information;
• enumerating order or profile identifiers;
• abusing promotional products;
• triggering costly top-ups;
• exporting excessive customer data;
• exhausting provider inventory or rate limits.

Controls may include:

• per-tenant and per-operation rate limits;
• spending and volume thresholds;
• payment and account risk checks;
• predictable-state validation;
• approval for high-risk bulk operations;
• anomaly monitoring;
• circuit breakers;
• inventory guards;
• manual review for exceptional patterns.

A technical rate limit alone is not a fraud strategy. Ten allowed requests can still be harmful if every request purchases an expensive product.

API versioning and change management

Connectivity services evolve. Products, networks, provider relationships and software interfaces change.

The provider should document:

• versioning approach;
• backwards-compatibility policy;
• deprecation period;
• release notes;
• breaking-change definition;
• sandbox availability before production change;
• method for announcing urgent changes;
• support for overlapping versions;
• treatment of enum additions and new optional fields.

Build tolerant readers, not careless readers

A consumer should normally tolerate a new optional field. It should not silently accept an unknown value that changes financial or lifecycle meaning.

For example, a newly introduced order status should move the record to an explicit unknown or review state rather than being treated as fulfilled.

Use machine-readable documentation

The OpenAPI Specification provides a standard format for describing HTTP APIs. A maintained specification can support client generation, validation, test tooling and documentation.

Machine-readable documentation is not automatically correct. Compare it with real sandbox behaviour and release notes.

Observability and operational monitoring

An integration is not complete until operators can see whether it works.

Technical metrics

• request count by endpoint and outcome;
• latency percentiles;
• timeout and connection-error rate;
• authentication failures;
• rate-limit responses;
• retry volume;
• webhook signature failures;
• webhook processing delay;
• queue depth and oldest message;
• dead-letter count.

Business metrics

• paid orders awaiting fulfilment;
• fulfilment success and time;
• profiles allocated but not delivered;
• installation or activation state where available;
• top-up completion time;
• refund and replacement rate;
• order-to-provider reconciliation differences;
• usage and invoice variance;
• product-level margin;
• support contacts per order.

Correlation identifiers

Link customer, payment, local order, provider order, profile and event records through stable identifiers. Propagate a correlation identifier through internal services and retain the provider's request or trace identifier when supplied.

A support agent should be able to begin with the customer's order number and reach the relevant technical evidence without searching several unrelated systems manually.

Alerts should identify action

“API errors increased” is less useful than:

“Provider order creation has exceeded the agreed failure threshold for ten minutes; 28 paid orders remain pending; automatic retries are paused; incident owner is Integration Operations.”

Each alert should identify severity, affected workflow, customer impact, responsible team and immediate action.

Handling provider outages

The customer experience should fail safely when the upstream service is unavailable.

Possible controls include:

• circuit breaker after repeated failures;
• queued fulfilment with a clear customer message;
• temporary withdrawal of affected products;
• prevention of further payment capture where fulfilment cannot be completed safely;
• status page and support notification;
• reconciliation when service returns;
• controlled manual fulfilment for approved cases;
• failover to another provider only when products and commercial rules are genuinely compatible.

Do not automatically switch to an alternative product with different coverage, activation rules or restrictions without customer and commercial controls.

Decide the payment behaviour in advance

For each failure point, specify whether the system will:

• keep the authorisation open;
• capture later;
• void the authorisation;
• issue an automatic refund;
• hold the order for manual review;
• offer the customer a choice.

This decision belongs to product, finance and customer operations, not only the API developer.

Sandbox and test-environment requirements

A useful sandbox should support more than one successful response.

Ask whether it can simulate:

• processing and delayed fulfilment;
• permanent failure;
• transient server error;
• request timeout;
• rate limiting;
• duplicate idempotency key;
• duplicate webhook;
• out-of-order webhook;
• invalid webhook signature;
• profile unavailable;
• package activation and expiry;
• usage thresholds;
• top-up success and failure;
• suspension and reactivation;
• invoice or usage export.

The provider should explain differences between sandbox and production, including product catalogue, authentication, rate limits, data retention and webhook delivery.

Testing strategy

Contract tests

Validate that requests and responses match the agreed schema, required fields, types and allowed values.

State-transition tests

Test allowed and rejected transitions. A cancelled order should not return to processing without a defined recovery flow.

Idempotency tests

Repeat the same order request before and after completion. Verify that only one business effect occurs.

Failure-injection tests

Create timeouts, delayed events, unavailable dependencies and partial internal failures. Confirm that the system reaches a recoverable state.

Security tests

Test tenant isolation, object-level authorisation, credential revocation, webhook signatures, replay handling, input limits and sensitive-data exposure.

Load and burst tests

Use volumes agreed with the provider. Test both ordinary throughput and bursts created by campaigns, travel disruption or bulk IoT operations.

End-to-end device tests

For representative products and devices, test the complete journey:

1. retrieve product;
2. create and pay for order;
3. receive profile information;
4. download and install the eSIM;
5. enable it;
6. register on a permitted network;
7. use the intended service;
8. observe usage or balance;
9. apply a permitted top-up or lifecycle operation;
10. reconcile the transaction.

An API test that stops at a 200 OK response has not tested mobile connectivity.

Financial reconciliation

Technical success and commercial correctness are different.

Create daily or periodic controls comparing:

• captured payments;
• local orders;
• provider orders;
• allocated profiles or SIMs;
• fulfilled packages;
• cancellations and refunds;
• usage charges;
• wholesale invoices;
• reseller commission;
• taxes and currencies.

Examples of exceptions

• payment captured, no provider order;
• provider order fulfilled, payment failed;
• two provider orders linked to one local order;
• refund issued, active package retained unexpectedly;
• top-up charged twice;
• usage exceeds the expected commercial rule;
• wholesale price differs from the imported catalogue snapshot;
• invoice contains an unknown profile or partner reference.

Every exception should enter a controlled queue with an owner, financial value and resolution history.

Documentation your team needs

A production integration needs more than endpoint reference pages.

Request and maintain:

• authentication guide;
• environment and credential process;
• OpenAPI or equivalent interface definition;
• data model and state descriptions;
• error catalogue;
• idempotency rules;
• rate limits;
• webhook security and retry policy;
• product and price change process;
• release and deprecation policy;
• support and escalation contacts;
• incident and maintenance process;
• reconciliation and invoice guide;
• data-protection and retention information;
• business-continuity information.

Internal documentation should add:

• architecture decision record;
• system-of-record matrix;
• sequence and state diagrams;
• secret-rotation procedure;
• operational dashboards and alerts;
• incident runbooks;
• manual fulfilment and refund controls;
• go-live and rollback process.

A practical go-live checklist

Architecture and data

• □Every core entity has a defined system of record.
• □Provider identifiers are stored separately from local identifiers.
• □State transitions and unknown outcomes are modelled explicitly.
• □Sensitive fields and retention rules are documented.

Orders and payments

• □Order creation has an idempotency strategy.
• □Timeout and duplicate scenarios have been tested.
• □Payment capture, void and refund behaviour is defined for each failure point.
• □Reconciliation detects mismatched payments and provider orders.

Webhooks and asynchronous processing

• □Signatures and timestamps are verified correctly.
• □Duplicate and out-of-order events are safe.
• □Events are stored before processing is acknowledged.
• □Failed processing reaches a visible retry or manual-review queue.
• □Polling or reconciliation covers missed events.

Security

• □No provider secret exists in a browser or mobile application.
• □Production and sandbox credentials are separate.
• □Credentials have least privilege and a tested rotation procedure.
• □Tenant and object-level authorisation have been tested.
• □Logs exclude secrets, payment data and unnecessary personal information.
• □Administrative and bulk actions are audited.

Operations

• □Technical and business dashboards are live.
• □Alerts identify an owner and action.
• □Support can trace a customer order to provider and profile references.
• □Provider escalation and outage procedures have been rehearsed.
• □Product withdrawal can be performed quickly.

Commercial readiness

• □Catalogue price changes are controlled.
• □Usage and invoices can be reconciled.
• □Live terms match activation, validity, refund and replacement behaviour.
• □Representative device and network tests have passed.
• □A rollback or launch-pause decision owner is named.

Common integration mistakes

Calling the provider directly from the mobile application

This exposes credentials or forces unsafe authentication compromises. Use a controlled backend.

Treating a timeout as a failed order

The order may have completed. Retrieve or reconcile it before creating another.

Using email or product names as identifiers

Names change and customer data should not become a technical key. Use immutable identifiers.

Assuming webhooks arrive once and in order

Design for retries, duplicates, delay and reordering.

Sending fulfilment twice

Duplicate events or retries can cause multiple emails and confusion. Make each side effect idempotent.

Exposing the QR code too broadly

Activation information should be available only to authorised customers and support roles.

Logging every payload without redaction

This can copy credentials, personal data and activation information into multiple log systems.

Mixing order and connectivity states

A fulfilled order can contain a profile that is not installed. An enabled profile can have an expired package. Keep the lifecycles separate.

Ignoring finance until month end

Daily exceptions are easier to investigate than thousands of unexplained differences on an invoice.

Building only the successful path

Most integration complexity exists in uncertain, delayed and partially completed operations.

How SIM24.biz fits into an API-led service

SIM24.biz supports businesses building branded SIM, eSIM and IoT connectivity propositions. An API-led model can allow the partner to retain its existing website, application, payments, CRM, analytics and customer relationship while integrating the required connectivity functions.

The correct integration boundary depends on the project. One partner may use a complete white-label customer journey. Another may use APIs for catalogue, fulfilment and lifecycle functions while owning the entire front end. A third may combine physical SIM and eSIM inventory with enterprise or IoT operations.

The precise endpoints, authentication methods, webhooks, lifecycle visibility, limits, sandbox functions and service levels available from SIM24.biz must be confirmed for the selected implementation and supplier combination. The schemas and endpoint names in this article are illustrative and must not be presented as current SIM24.biz API documentation.

A responsible technical discovery should define:

• the target customer journey;
• systems of record;
• required products and markets;
• integration and event flows;
• payment and reconciliation model;
• security and data responsibilities;
• pilot scenarios;
• operational ownership after launch.

Conclusion

An eSIM API integration is successful when customers receive reliable connectivity and the business can explain every order, profile, payment and exception.

The API call itself is only one part of that outcome. The complete design must handle asynchronous fulfilment, independent lifecycle states, idempotent operations, verified webhooks, uncertain responses, secure credentials, operational monitoring and financial reconciliation.

The best architecture creates clear boundaries. The brand owns its customer and commercial logic. The integration layer controls external dependencies. The provider supplies defined platform, provisioning and connectivity capabilities. Every party can identify which state it knows and which action it owns.

Build the failed paths before launch, not after the first paid customer is waiting for a profile.

Frequently asked questions

What is an eSIM API?

An eSIM API is a business interface through which an authorised partner can access functions such as product retrieval, ordering, profile fulfilment, status, usage, top-ups or lifecycle management. Its exact scope depends on the provider.

Does an eSIM API connect directly to the eUICC?

Normally, a retail or white-label business API connects to the provider platform. Secure profile delivery to the eUICC uses the relevant provisioning architecture and components, such as the SM-DP+ and Local Profile Assistant in the consumer model.

Why are eSIM orders asynchronous?

The provider may need to allocate inventory, complete provisioning work or coordinate other systems. Returning a pending resource allows the customer request to finish without waiting indefinitely.

What is an idempotency key?

It is a unique value representing one intended state-changing operation. When the same request must be retried, reusing the key helps prevent an unintended duplicate business effect where the provider supports this behaviour.

Should I retry a timed-out eSIM order?

First treat the result as unknown. Retrieve the order using the partner reference or the provider's idempotency mechanism. Retry only according to the documented rules and use the same identifier for the same intended operation.

How should an eSIM webhook be secured?

Verify the provider's signature over the raw request according to its documented scheme, check a signed timestamp or replay control, restrict payload size, store the event identifier and process the event idempotently. Mutual TLS may be suitable for some higher-assurance integrations.

Are webhooks guaranteed to arrive once?

Do not design on that assumption. Consumers should tolerate duplicate, delayed and out-of-order events and should use reconciliation to find missed changes.

Should the QR code be stored?

Store only what is required for the supported customer and recovery journey, protect it as sensitive fulfilment information and restrict access. Confirm retention and redisplay rules with the provider.

What should an eSIM API sandbox include?

It should support representative success and failure scenarios, including asynchronous completion, duplicate requests, webhook retries, invalid signatures, rate limits, lifecycle changes and reconciliation data.

How should API credentials be stored?

Keep them in a server-side secret-management system, separate environments and privileges, rotate them under a tested procedure and never place them in browser or mobile application code.

How can we change eSIM providers later?

Keep provider-specific logic behind an integration boundary, use internal identifiers and domain models, retain complete data exports and negotiate transition rights. Active profiles may still require a technical migration or replacement rather than a simple database change.

Is an API integration better than a complete white-label platform?

It offers more control over the customer experience and systems, but requires development and permanent operational ownership. A complete white-label platform may enable a faster launch. The right model depends on differentiation, resources and scale.

Connect eSIM and SIM services to the systems you already own

SIM24.biz helps partners define branded connectivity journeys, integration boundaries and pilot requirements around their existing commerce and customer platforms.

Talk to SIM24.biz about the appropriate API or white-label model for your service.

Sources

1. GSMA, “SGP.22 v2.7, eSIM Consumer Technical Specification”: https://www.gsma.com/solutions-and-impact/technologies/esim/gsma_resources/sgp-22-v2-7/
2. GSMA, “SGP.31 v1.3, eSIM IoT Architecture and Requirements”: https://www.gsma.com/solutions-and-impact/technologies/esim/gsma_resources/sgp-31-v1-3/
3. GSMA, “SGP.32 v1.3, eSIM IoT Technical Specification”: https://www.gsma.com/solutions-and-impact/technologies/esim/gsma_resources/sgp-32-v1-3/
4. IETF, “RFC 9110, HTTP Semantics”: https://www.rfc-editor.org/rfc/rfc9110.html
5. IETF, “RFC 9700, Best Current Practice for OAuth 2.0 Security”: https://www.rfc-editor.org/rfc/rfc9700.html
6. IETF, “RFC 8725, JSON Web Token Best Current Practices”: https://www.rfc-editor.org/rfc/rfc8725.html
7. OpenAPI Initiative, “OpenAPI Specification v3.1.1”: https://spec.openapis.org/oas/v3.1.1.html
8. Cloud Native Computing Foundation, “CloudEvents Specification”: https://github.com/cloudevents/spec/blob/main/cloudevents/spec.md
9. OWASP Foundation, “OWASP API Security Top 10, 2023”: https://owasp.org/API-Security/editions/2023/en/0x11-t10/
10. European Union, “Regulation (EU) 2016/679, General Data Protection Regulation”: https://eur-lex.europa.eu/eli/reg/2016/679/oj/eng
11. European Data Protection Board, “Guidelines 07/2020 on the concepts of controller and processor in the GDPR”: https://www.edpb.europa.eu/our-work-tools/our-documents/guidelines/guidelines-072020-concepts-controller-and-processor-gdpr_en