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.

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. This requirement is noted in the product details when retrieving the product catalog.

KYC Process Flow​

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

  2. 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...
        ]
      }
    }

  3. Share the KYC_URL with your customer so they can complete the identity verification process through the provided link.

  4. 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:

  1. 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"
      }
    }'

  2. The notification email will be sent automatically only after the KYC process has been completed and the order transitions to the Completed state.

  3. You can periodically check the order status using the Get Order Information endpoint to know when the KYC verification has been completed.

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​

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