Getting the Product List

The first step when integrating to the MobiMatter API is to fetch the products. MobiMatter's eSIM products are all pre-packaged, and are differentiated by provider, data allowance, package validity and country coverage.

MobiMatter offers 3 kinds of products currently, indicated by the productCategory attribute on the product model.

Product Categories

ProductCategory	Description
esim_realtime	New eSIM sales. All products under this category will return a new QR code with the specific package assigned to it.
esim_addon	eSIM Topups. All products under this category will add the package onto an existing eSIM previously bought with MobiMatter of the same provider.
esim_replacement	eSIM replacements. All products under this category will return a new QR code, and assign the existing package from an eSIM previously bought with MobiMatter of the same provider.

Product Families

Each product is assigned a productFamilyId, this value will allow you to determine which packages you can interchangeably top-up. In other words, if two products share the same product family, you can top-up one with the other.

Product response caching

Each product has an updated field, which denotes when was this product last updated. This field can be useful to cache product definitions on your end, and bust the cache when the product is updated again.

Example Request

curl -L "https://api.mobimatter.com/mobimatter/api/v2/products" -H "api-key: xyz" -H "MerchantId: deadbe-eef5-75AC-1A5F-69C92154013b"

Example Product

{
    "productId": "49951e61-dead-beef-9f8b-69b94975509b", 
    "rank": 42667, // A MobiMatter quality factor, higher is better. Can be useful for product sorting by quality.
    "productCategoryId": 1, 
    "productCategory": "esim_realtime", // see above table
    "providerId": 22, 
    "networkListId": 1,
    "providerName": "Vinaphone",
    "providerLogo": "https://mobimatterstorage.blob.core.windows.net/mobimatter-assests/assets/vinaphone.png",
    "retailPrice": 8.99, // Merchant's set retail price, can be adjusted in the Partner Portal
    "wholesalePrice": 7.6, // Merchant's cost for this product, this amount will be deducted from the wallet when purchasing
    "currencyCode": "USD", // USD only transactions are supported
    "created": "2023-02-20T15:53:38.107Z",
    "updated": "2023-06-20T04:36:41.5249522Z", // Last update to this product, useful for caching
    "regions": [
        "Asia"
    ],
    "countries": [ // ISO 2-letter country codes for country coverage
        "VN"
    ],
    "displayAttributes": [],
    "productDetails": [
        {
            "name": "PLAN_TITLE",
            "value": "Vietnam 60 GB"
        },
        {
            "name": "PLAN_DATA_LIMIT",
            "value": "60"
        },
        {
            "name": "PLAN_DATA_UNIT",
            "value": "GB"
        }
        {
            "name": "PLAN_VALIDITY", // In hours
            "value": "360"
        },
        {
            "name": "TAGS",
            "value": "[{\"color\":\"#464545\",\"item\":\"BEST QUALITY\"}]"
        },
        {
            "name": "PLAN_DETAILS",
            "value": "{\"heading\":\"BEST DEAL - LOCAL VIETNAM eSIM FOR TOURISTS\",\"description\":\"Usage limitation: 4GB per day for 15 days.\",\"items\":[\"Tourist eSIM package from Vietnamese mobile operator Vinaphone. Voice calls or SMS is not included.\",\"The bundle contains 4GB per day of high-speed data for 15 days.\",\"Connects to Vinaphone network with 4G LTE speeds.\",\"Validity of the package will start upon scanning the QR code and downloading the eSIM to your phone.\",\"Unlimited data - if 4GB daily allowance is fully consumed the line will continue to work with throttled speeds until the next day.\",\"Simply scan the QR code to download and use the eSIM. No other activation or registration steps needed.\",\"One time prepaid package. No auto-renewals, no contracts.\",\"Usable only with eSIM compatible phones and tablets which are not carrier locked. If in doubt, please check the FAQ section.\",\"Please start using the eSIM no more than 1 month after purchase.\"]}"
        },
    ]
}

Getting the networks that a products connects to

Click for relevant API endpoint

Each product that has network information will have a networkListId attribute. This ID identifies the set of mobile networks that this eSIM product can connect to. You can query the product's networks and retrieve detailed information about available networks.

Making a Network List Request

To retrieve the networks for a specific product, use the following endpoint:

curl -L "https://api.mobimatter.com/mobimatter/api/v2/products/{productId}/networks" \
-H "api-key: YOUR_API_KEY" \
-H "MerchantId: YOUR_MERCHANT_ID"