Let users subscribe with their mobile number: Ideamart OTP explained

Not everyone has a card, but almost everyone in Sri Lanka has a mobile number. With Dialog Ideamart, your users can sign up with just their number and pay through their mobile bill or balance. No card and no bank app.

We used this approach for Divi Gamana, a multilingual astrology readings platform. Users enter their mobile number, confirm a one-time PIN and subscribe for a small daily fee that is charged to their mobile account. In this post we walk through how it works.

The building blocks

• OTP API: sends a PIN to the user's number and confirms it.
• Subscription API: tracks who is subscribed to your app.
• SMS API: sends messages to your subscribers.
• Charging API (CaaS): charges the user's mobile account, for one-time or recurring payments.

Before you write any code, create an Ideamart account and provision your application in the developer portal. You will get an Application ID and a password, which every API call needs.

Step 1: Request a PIN

Ask the user for their mobile number, then send it to the OTP request API from your back end.

POST https://api.ideamart.io/subscription/otp/request

{
  "applicationId": "APP_001100",
  "password": "your-app-password",
  "subscriberId": "tel:94771234567",
  "applicationHash": "8f14e45f-ceea-4d6a",
  "applicationMetaData": {
    "client": "WebSite",
    "device": "Chrome on Android",
    "os": "Android 14",
    "appCode": "https://example.lk"
  }
}

If it works, you get statusCode S1000 and a referenceNo. Save the referenceNo, because you need it in the next step. If the number is already subscribed you get E1351 instead, so you can sign the user straight in.

Tip

Always call Ideamart from your back end, on a server with a static IP. Never put your Application ID and password in front-end code.

Step 2: Verify the PIN

The user receives the PIN by SMS and types it into your site. Send it with the referenceNo to the verify API.

POST https://api.ideamart.io/subscription/otp/verify

{
  "applicationId": "APP_001100",
  "password": "your-app-password",
  "referenceNo": "3b84346f63899a32ec742a676532ec74dffe4f5",
  "otp": "123564"
}

A successful response contains subscriptionStatus REGISTERED and a subscriberId. The subscriberId is a masked version of the user's number. Store it, and use it for every later call to the SMS, Subscription and Charging APIs.

Handle the common errors

• E1850: the PIN is wrong. The user can try up to 3 times.
• E1851: the PIN has expired. A PIN is valid for 60 minutes.
• E1852: too many attempts. Ask the user to request a new PIN.

Ideamart can return HTTP 200 even when something goes wrong, so always check the statusCode in the response body, not just the HTTP status.

Step 3: Send a welcome SMS

POST https://api.ideamart.io/sms/send

{
  "applicationId": "APP_001100",
  "password": "your-app-password",
  "destinationAddresses": ["tel:hu3b84346f63899a32ec742a666503a02a4dffe4f5"],
  "message": "Welcome! Your subscription is active."
}

The destination is the masked subscriberId, not the plain number. Ideamart maps it back to the right phone.

What we learned building Divi Gamana

• Keep the sign-in screen to one field and one button. Every extra step loses people.
• Show the price clearly before the user confirms. Divi Gamana shows the daily fee right under the number field.
• Make unsubscribing easy and visible. It builds trust, and users expect it.
• Use the Ideamart simulator during development, then test in limited production before going fully live.
• Log every request and response with your applicationHash, so you can trace problems quickly.

Carrier billing opens your product to customers who would never enter card details online. If you're planning a subscription service, SMS alerts or a USSD menu, we can help you build it on Ideamart.