Placing an Order

Placing an order is a two-step process. You will need first to create the order, which will reserve an eSIM on MobiMatter's end. With the order id, you can trigger a "CompleteOrder" command which will complete the order, and let you access the eSIM's details.

Order Creation

Click for relevant API endpoint

Creating an order essentially reserves an eSIM on MobiMatter's backend for the merchant. Upon creation, an amount equal to the wholesalePrice of the product will be authorized from the merchant's wallet.

In return, the merchant gets an OrderId, which will allow him to interact with the order.

Example

curl -L -X POST 'https://api.mobimatter.com/mobimatter/api/v2/order' \
-H 'Content-Type: application/json' \
-H 'api-key: <API_KEY_VALUE>' \
-H 'merchantId: <MerchantId>' \
--data-raw '{
  "productId": "9f0d2dcb-31d7-46d0-846d-bb68aa710e7e",
  "productCategory": "esim_realtime | esim_delayed | physical_sim | esim_addon | esim_replacement",
}'

Response Codes

Code	Meaning	What to do
`200`	Order created. `result.orderId` is your handle for completion.	Persist the `orderId` before calling Complete Order.
`400`	The request was rejected. The `message` field carries the reason.	Surface `message` — it is the only specific information available.
`402`	Insufficient wallet balance to authorize the order.	Top up your wallet in the Partner Portal or by bank transfer.
`429`	The product is out of stock.	Not a rate limit — retrying will not help. Offer the customer a different product.
`455`	The product's provider is temporarily unavailable.	Temporary and not specific to the product. Retry later or offer an alternative.

Creating a topup order

Creating a topup order is easy! Just pass the eSIM's OrderId you want to top up as the addOnOrderIdentifier parameter.

info

You can top-up an eSIM only if the original product assigned to it and the top-up product requested share the same productFamilyId value. See Finding Top-up Products for how to discover which products are compatible.

caution

addOnOrderIdentifier is always the original eSIM order — the esim_realtime order the customer first bought. It is never the most recent top-up, and never a previous replacement.

If a customer buys order A and tops it up twice, both top-up orders carry addOnOrderIdentifier: A. If they then receive a replacement, that replacement also carries A, and any later top-up still carries A.

Store the original order id against the customer's eSIM once, and reuse it for every subsequent top-up and replacement.

Order Expiry

Orders get expired after certain time spent in the Created state. Time to expire varies by product but it is not less than 20 minutes. Once an order gets expired - funds authorized are returned to the merchant's wallet.

Order Cancellation

Click for relevant API endpoint

A merchant can choose to cancel an order in the Created state. Funds authorized are returned to the merchant's wallet.

Order Completion

Click for relevant API endpoint

Calling this endpoint will signal MobiMatter this order should be completed, merchant wallet would be deducted and the merchant will have access to the eSIM details.

eSIMs that require KYC

Click for relevant API endpoint

Some eSIM products require Know Your Customer (KYC) verification with identity documents before they can be activated. These are the products in the esim_delayed category, and they are the only products that return a KYC_URL.

Because esim_delayed is one of the categories that honours callbackUrl, you can receive KYC completion by webhook rather than polling. See Order Completion Webhooks.

KYC Process Flow

When you complete an order for a KYC-required eSIM using the CompleteOrder endpoint, the API will respond with a 2xx status code, but the order will be in the Processing state rather than Completed.

In this case, the order line item details will include a KYC_URL parameter that you must share with your customer.

Example response excerpt:

{
  "orderState": "Processing",
  "orderLineItem": {
    "lineItemDetails": [
      {
        "name": "KYC_URL",
        "value": "https://kyc-verification.example.com/verify/a1b2c3d4"
      },
      // Other line item details...
    ]
  }
}

Share the KYC_URL with your customer so they can complete the identity verification process through the provided link.
If the KYC is not completed within 24 hours, the order will be cancelled and the funds will be refunded to your wallet.

Notification Integration

While the KYC process is ongoing, you can schedule an email notification to be sent once the KYC verification is completed:

After receiving the Processing status, use the notification API endpoint to set up an automatic email that will be sent to your customer only after the KYC process completes successfully.

curl -L -X POST 'https://api.mobimatter.com/mobimatter/api/v2/email' \
-H 'Content-Type: application/json' \
-H 'api-key: <API_KEY_VALUE>' \
-H 'merchantId: <MerchantId>' \
--data-raw '{
  "orderId": "YOUR_ORDER_ID",
  "customer": {
    "name": "Customer Name",
    "email": "customer@example.com"
  }
}'

The notification email will be sent automatically only after the KYC process has been completed and the order transitions to the Completed state.
To know when KYC has completed, pass a callbackUrl when creating the order and let the webhook tell you. Polling Get Order Information is the fallback for when the webhook retry window has been exhausted, or when you cannot expose a public endpoint.

caution

If KYC is not completed within 24 hours, the order is cancelled and your wallet is refunded. If you had already charged your own customer, you will need to refund them — MobiMatter refunds your wallet, not your customer.

Order Label

This API endpoint allows you to specify an optional label for an order. The purpose of this order label is to allow you to specify an external identifier which would help you to easily search for the order in the merchant portal's "Order History & Topup" section. We encourage you not to use any personal identifying information for the order label.

Example eSIM Response

{
  "statusCode": 200,
  "result": {
    "orderId": "XYZ-234323",
    "orderState": "Completed",
    "currencyCode": "USD",
    "created": "2023-01-28T21:26:03.847",
    "updated": "2023-01-28T21:28:14.95",
    "orderLineItem": {
      "productId": "c0654cf2-0172-4909-91d1-37ca37e6f195",
      "productCategory": "esim_realtime",
      "title": "Global 13 GB",
      "provider": "15",
      "providerLogo": "https://mobimatterstorage.blob.core.windows.net/mobimatter-assests/assets/3HK.png",
      "retailPrice": 39.990000,
      "wholesalePrice": 35.500000,
      "lineItemDetails": [
        {
          "name": "ACTIVATION_CODE",
          "value": "XXXXX"
        },
        {
          "name": "PHONE_NUMBER",
          "value": "+8526000000"
        },
        {
          "name": "ICCID",
          "value": "8980000000000"
        },
        {
          "name": "LOCAL_PROFILE_ASSISTANT",
          "value": "LPA:1$hhk.prod.ondemandconnectivity.com$XXXXXX"
        },
        {
          "name": "ACCESS_POINT_NAME",
          "value": "mobile.lte.three.com.hk"
        },
        {
          "name": "SMDP_ADDRESS",
          "value": "hhk.prod.ondemandconnectivity.com"
        },
        {
          "name": "QR_CODE",
          "value": "data:image/png;base64,dskfjdskdfjskdcjsdk=="
        }
      ],
      "oneClickInstall": {
        "ios": "https://esimsetup.apple.com/esim_qrcode_provisioning?carddata=LPA:1$hhk.prod.ondemandconnectivity.com$XXXXXX",
        "android": "https://esimsetup.android.com/esim_qrcode_provisioning?carddata=LPA:1$hhk.prod.ondemandconnectivity.com$XXXXXX"
      }
    },
    "label": "YOUR_ORDER_LABEL"
  }
}

Line Item Details Reference

The lineItemDetails array on a completed order carries the eSIM's credentials as { name, value } pairs. Look values up by name — not every key is present on every product, and the order of the array is not guaranteed.

Name	Value
`LOCAL_PROFILE_ASSISTANT`	The LPA activation string, `LPA:1$smdp.host$MATCHING-ID`. This is the canonical activation credential.
`QR_CODE`	A `data:image/png;base64,...` image of the LPA, ready to render directly.
`ICCID`	The eSIM's identifier. Also the key for Get Order by ICCID.
`SMDP_ADDRESS`	The SM-DP+ server hostname.
`ACTIVATION_CODE`	The matching id portion of the LPA.
`ACCESS_POINT_NAME`	APN, for providers that require manual APN setup.
`PHONE_NUMBER`	The line's phone number, where the product provides one.
`KYC_URL`	Present on `esim_delayed` orders in the `Processing` state. Share it with your customer to begin identity verification.

One-Click eSIM Installation

Completed eSIM orders include a oneClickInstall object on the orderLineItem with platform-specific links that launch the device's native eSIM install flow, removing the need to scan the QR code. It is built from the eSIM's LPA (LOCAL_PROFILE_ASSISTANT) and is present only when an LPA is available.

ios — open on iOS 17.4+ to start the system eSIM install.
android — open on supported Android devices to start the system eSIM install.

The same oneClickInstall object is returned by Get Order Information and Get Order by ICCID.

Refund Order

Click for relevant API endpoint

After an order is completed, in some cases, you may need to refund it. MobiMatter provides APIs to check if an order is eligible for refund and to process the refund if eligible.

Checking Refund Eligibility

Before attempting to refund an order, you should check if it's eligible for refund. This endpoint will tell you if the order can be refunded, any applicable refund fee, and if not eligible, the reason why.

curl -L -X GET 'https://api.mobimatter.com/mobimatter/api/v2/order/{orderId}/refund/eligibility' \
-H 'api-key: <API_KEY_VALUE>' \
-H 'merchantId: <MerchantId>'

Example Response

{
  "statusCode": 200,
  "result": {
    "isEligible": true,
    "fee": 2.5,
    "reason": null
  }
}

The response includes:

isEligible: Boolean indicating whether the order can be refunded
fee: If applicable, the fee that will be charged for processing the refund
reason: If not eligible, this field explains why the refund cannot be processed

Processing a Refund

If the order is eligible for refund, you can proceed with the refund process using the refund endpoint.

curl -L -X PUT 'https://api.mobimatter.com/mobimatter/api/v2/order/refund' \
-H 'Content-Type: application/json' \
-H 'api-key: <API_KEY_VALUE>' \
-H 'merchantId: <MerchantId>' \
--data-raw '{
  "orderId": "YOUR_ORDER_ID"
}'

A successful refund request will return a 2xx status code indicating the order has been marked for refund. If the order is ineligible for refund, you'll receive a 400 status code.

Note that once a refund is processed, it cannot be reversed. Any refund fees indicated in the eligibility check will be applied during the refund process.

Order Lifecycle

lifecycle

Order Creation​

Example​

Response Codes​

Creating a topup order​

Order Expiry​

Order Cancellation​

Order Completion​

eSIMs that require KYC​

KYC Process Flow​

Notification Integration​

Order Label​

Example eSIM Response​

Line Item Details Reference​

One-Click eSIM Installation​

Refund Order​

Checking Refund Eligibility​

Example Response​

Processing a Refund​

Order Lifecycle​

Order Creation

Example

Response Codes

Creating a topup order

Order Expiry

Order Cancellation

Order Completion

eSIMs that require KYC

KYC Process Flow

Notification Integration

Order Label

Example eSIM Response

Line Item Details Reference

One-Click eSIM Installation

Refund Order

Checking Refund Eligibility

Example Response

Processing a Refund

Order Lifecycle