Mobily eSIM is an industry-standard digital SIM that allows users to activate a cellular plan from Mobily without having to use a normal physical SIM.
Mobily eSIM APIs allows customers to purchase and activate the Mobily cellular plan with digital SIM. Currently customers can use the Mobily digital channels like Web Portal and Mobile App to order new digital SIM and activate the same. Mobily digital partners can integrate with Mobily eSIM APIs and provide the services to purchase and activate the Mobily Digital SIM.
1. Mobily Products
System shows the list of available Mobily products from the Content Management System (WCM).
2. Authentication
It is the process to authenticate the systems and allow the access of Mobily eSIM APIs. System needs to authenticate with the given authentication details and consumer the APIs. Channel system to adhere all the Mobily Security guidelines. Please refer the API documentation for authentication process and sample input & output details.
3. Mobily Products Details
Mobily provide the Graph QL APIs to inquiry the products catalogue and products details. Channel system consume the same to retrieve the sellable products and display the details to customers.
Please refer the below APIs for complete details.
API details:
Get Products details
API URL:
/catalog-agg-query/graphql
Create Shopping cart:
System to create a shopping kart with the product selected by customer.
API URL:
/api/shopping-cart/v3/shoppingCart
Swagger Link:
API URL:
/mobily-shopping-cart-management/api/update-and-validate
Swagger Link:
<<Product Offer Qualification >>
4. Number Option
Customer can purchase a new Mobily number or purchase a package with his / her number (MNP Port In).
API details:
API URL:
/checkout-api/v3/checkout/structure
Swagger Link:
<<Generate checkout Structure >>
API URL:
/checkout-api/v3/checkout/captureData
Swagger Link:
<<Capture the number option >>
5. SIM Options
Customers can purchase physical SIM or Digital SIM.
API details:
API URL:
/checkout-api/v3/checkout/structure
Swagger Link:
<<Generate checkout Structure >>
API URL:
/checkout-api/v3/checkout/captureData
Swagger Link:
<<Capture the number option >>
6. TCC Eligibility
As per the CST guidelines there are certain limitations on number of service lines per customer. So, channel / digital partner need to check the customer eligibility to proceed with new service line purchase. Partner needs to call the Mobily TCC eligibility service to check the eligibility and proceed further.
Please refer the below APIs for complete details.
API details:
API URL:
/checkout-api/v3/checkout/structure
Swagger Link:
<<Generate checkout Structure >>
API URL:
/bmi-tcc-eligibility/services/tcc/eligibilityCheck
Swagger Link:
API URL:
/bmi-customer-management/services/installedbase/getCustomerProductDetails
Swagger Link:
<<Get Customer Account/Product Details >>
API URL:
/checkout-api/v3/checkout/captureData
Swagger Link:
<<Capture section(TCCEligibiliyCheck) >>
7. Number Reservation
Mobily enables customers to select the desired Mobile number from the available pool of numbers. Based on the selected package customers may choose the vanity numbers as well.
API details:
API URL:
/checkout-api/v3/checkout/structure
Swagger Link:
<<Generate checkout Structure >>
API URL:
/resource-pool-management/services/resourcePoolManagement/AvailabilityCheck
Swagger Link:
<<Get msisdn(if ChooseNumber exists) >>
API URL:
/resource-pool-management/services/resourcePoolManagement/Reservation
Swagger Link:
API URL:
/checkout-api/v3/checkout/captureData
Swagger Link:
<<Capture section(Number Reservation) >>
8. Overdue bill
As per the Mobily business process customer need to pay all the previous dues if customer would like to purchase new service line. Channel / Digital Partner to check with Mobily if any previous overdue bills are existing in Mobily system for the customer. Overdue bill check is required if customer is purchasing a postpaid service.
If any overdue bills are there, then partner to show a proper error message to customer. So, use can navigate to Mobily portal and do the overdue payment.
API details:
API URL:
/checkout-api/v3/checkout/structure
Swagger Link:
<<Generate checkout Structure >>
API URL:
/bmi-customer-unpaidbills/services/customer/dues
Swagger Link:
API URL:
/api/shopping-cart/v3/shoppingCart/{shoppingCartId}
Swagger Link:
<<Patch Unpaid Bills Shopping Cart >>
API URL:
/checkout-api/v3/checkout/captureData
Swagger Link:
<<Capture section(OverdueBills) >>
API URL:
/checkout-api/v3/checkout/structure
Swagger Link:
9. Package eligibility
Mobily is having different business rules for different packages. Partner system to validate whether customer is eligible for the selected package or not, by calling Mobily’s package eligibility service. Customer able to proceed further if he / she is eligible to purchase the selected package or else system to show the proper error message.
10. Security Deposit
Security deposit is required if customer is trying to purchase a postpaid package. System to check the required security deposit amount and show the same to customer. Once customer accepts to pay the same then only customer can proceed further.
API details:
API URL:
/bmi-customer-security-deposit/services/deposit/get
Swagger Link:
API URL:
/api/shopping-cart/v3/shoppingCart/{shoppingCartId}
Swagger Link:
<<Security deposit_Patch API >>
API URL:
/checkout-api/v3/checkout/captureData
Swagger Link:
<<Capture section(SecurityDeposit) >>
API URL:
/checkout-api/v3/checkout/structure
Swagger Link:
11. OTP Verification
It is One time Pin code verification process which is required to validate the customer contact details. If customer is already existing in Mobily then system to show the existing service lines to customer and proceed with the OTP verification process with the line selected by customer. If customer is new to Mobily then Mobily to check with Tahaqoq to validate whether customer provided MSISDN and ID number are related or not? If it is valid then System sends the OTP to the same MSISDN and to verify the customer number. OTP verification process is mandatory for all customers.
API details:
API URL:
/bmi-customer-management/services/installedbase/getCustomerProductDetails
Swagger Link:
<<Get Customer(if OTPVerification exists) >>
API URL:
/mobily-otp-services/services/otp/generation
Swagger Link:
API URL:
/mobily-otp-services/services/otp/regeneration
Swagger Link:
API URL:
/mobily-otp-services/otp-rayah/validate
Swagger Link:
API URL:
/checkout-api/v3/checkout/captureData
Swagger Link:
<<Capture section(OTPVerification) >>
API URL:
/checkout-api/v3/checkout/structure
Swagger Link:
12. Nafath
Nafath is a government service to validate the customer identity. Partner system to use the Mobily Services for Nafath verification process. It is customer responsibility to have the Nafath app and perform the verification. Partner system to input the webhook URI while calling Nafath random number generation. Once customer complete face verification in Nafath App, partner system receives the Nafath verification status to the same webhook URI which is given by partner while calling random number service. Refer the Nafath status response for details. Partner should provide the basic auth for webhook.
API details:
API URL:
/cem/nafath/auth/v1/initiate
Swagger Link:
<<Generate Nafath Random Number >>
API URL:
/cem/nafath/auth/v1/tokeninfo
Swagger Link:
API URL:
/checkout-api/v3/checkout/captureData
Swagger Link:
<<Capture section(OTPVerification) >>
API URL:
/checkout-api/v3/checkout/structure
Swagger Link:
13. TCC Registration
As per the CST guide lines any new service line activation should be registered with TCC. Partner system use the Mobily services to register the new service line details with TCC.
API details:
API URL:
/bmi-sim-details/services/sim/get
Swagger Link:
API URL:
/bmi-tcc-eligibility/services/tcc/register
Swagger Link:
API URL:
/checkout-api/v3/checkout/captureData
Swagger Link:
API URL:
/checkout-api/v3/checkout/structure
Swagger Link:
14. Delivery Details
Customer should provide the contact details to proceed with purchase.
API details:
API URL:
/checkout-api/v3/checkout/captureData
Swagger Link:
<<Capture section (DeliveryDetails) >>
15. Payment
Customer need to complete the payment to submit new eSIM Order. Channel / Digital partner to use the Mobily payment APIs and follow the payment process. Refer the sequence diagram and the APIs for more details.
API details:
API URL:
/OrderGenerator/postProductOrder
Swagger Link:
API URL:
/api/payment/v2/createSession
Swagger Link:
Mobile App:
Portal:
Create Session and Update CC Details using MPGS Java Script
API URL:
/api/payment/v2/createPayment
Swagger Link:
<<3D enrollment(passing Session ID & Payment Trans ID),>>
System Open HTML in browser which redirects the customer to bank portal for OTP verification.
API URL:
/api/payment/v2/confirmPayment
Swagger Link:
<<ProceedPayment (Payment Details, Saving Flage, FCM Token)>>
16. Order
Once payment is success Channel / Digital partner system to submit the order to Mobily and show the success message to customer. Mobily performs the remaining process like order fulfillment, Service line activation, digital SIM QR code generation and eContract etc.
17. QR Code
It is eSIM QR code required to install the digital sim in compatible mobiles. Channel / Digital Partner system to inquiry Mobily to retrieve the QR code and show the same to customer. Channel / Digital Partner system can re-inquiry for QR code if any delay in activation process.
API details:
API URL:
/mobily-qr-code/services/qr/get
Swagger Link:
Please find the below flow which denotes the Mobily Digital SIM activation process.
Sequence Diagram:
