Skip to main content

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",
}'

Creating a topup order​

Creating a topup order is easy! Just pass the eSIM's OrderId you want to top up as the addOnIdentifier 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.

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.

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​

{
  "isSuccess": true,
  "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=="
        }
      ]
    },
    "label": "YOUR_ORDER_LABEL"
  }
}

Refund Order​

This is currently in a beta phase and available to select merchants. If you wish to get access to the refund API, please contact us.

Order Lifecycle​

lifecycle