This API will be used by Telco who only needed redirect url to Telco's subscription page. The subscription process including HE + OTP will be handled directly by Telco.

Sample request :

curl -X GET "https://{domain}/api/v1/ext/{CHANNEL}/{TELCO}/{SERVICE}/subscribe?apikey={APIKEY}&clickid={PIXEL}"

Note: API request is made over HTTP(S).

This API is used for telco providers that require the DCB process via OTP verification. The API will send an OTP code for the next step in the process.

Sample request :

curl -X GET "{domain}/api/v1/ext/{CHANNEL}/{TELCO}/{SERVICE}/send/otp?apikey={APIKEY}&clickid={PIXEL}&msisdn={MSISDN}"

Note: API request is made over HTTP(S).

This API is used for telco providers that require the DCB process via OTP verification. This API will used to verify the OTP code that has been previously sent to the customer and this process will complete the subscription initiated by the customer.

Sample request :

curl -X GET "{domain}/api/v1/ext/{CHANNEL}/{TELCO}/{SERVICE}/otp/subscribe?apikey={APIKEY}&otp_key={OTP_KEY}&otp_value={OTP_VALUE}"

Note: API request is made over HTTP(S).

Complete (full flow) subscription integration guide for the FSC – XL merchant, version 2 (DCB v2), using the /api/v2/ext/* endpoints.

Key difference from V1: every request (except Request Token) requires a Bearer Token in the Authorization header. The token is obtained first through the Request Token endpoint using Basic Auth.

Endpoint call order:

• Request Token — obtain a Bearer Token via Basic Auth (client id & client secret).
• Sub Request Pin (Send OTP) — send an OTP to the customer; returns the otp_key.
• Subscribe Confirm OTP — verify the OTP (otp_key + otp_value from SMS 99876).
• Unsubscribe — cancel the subscription.

Flow Summary: Request Token → Send OTP → SMS 99876 → Confirm OTP → Subscription Active

2. Authentication

2.1 Basic Auth (Request Token only)

The Request Token endpoint uses HTTP Basic Auth. The username is the merchant's client id and the password is the client secret. Credentials are Base64-encoded in the format username:password and sent in the Authorization header.

Authorization header (Base64 result):

Authorization: Basic WU9VUl9DTElFTlRfSUQ6WU9VUl9DTElFTlRfU0VDUkVU

2.2 Bearer Token (other endpoints)

The token obtained from Request Token is sent as a Bearer Token on all subsequent endpoints (Send OTP, Confirm OTP, Unsubscribe), via the header:

Authorization: Bearer <token>

IMPORTANT: The Bearer token expires every 1 hour. Once expired, call Request Token again to obtain a new token.

3. Common Parameters

Values inside curly braces { } are dynamic and must be replaced with actual values when making the call.

4. Integration Steps

Step 1 — Request Token GET

Obtain a Bearer Token using Basic Auth.

https://api.airpay.mobi/api/v2/ext/ID/wap/{service}/YOUR_API_KEY/token/

Authentication: Basic Auth — username = clientId, password = clientSecret

Result: The response contains data.token. This token is used as the Bearer Token in the next steps (in Postman it is automatically saved to the xToken variable).

Step 2 — Sub Request Pin (Send OTP) GET

Send an OTP code to the customer.

https://api.airpay.mobi/api/v2/ext/wap/XL/{service}/send/otp?apikey=YOUR_API_KEY&clickid={clickid}&msisdn={msisdn}

Headers: apikey: {apiKey} · Authorization: Bearer {token}

Result: Returns the otp_key, and the customer receives an SMS containing the OTP code from 99876.

Step 3 — Subscribe Confirm OTP GET

Verify the OTP to activate the subscription.

https://api.airpay.mobi/api/v2/ext/wap/XL/{service}/otp/subscribe?apikey=YOUR_API_KEY&otp_key={otpKey}&otp_value={otpValue}

Headers: apikey: {apiKey} · Authorization: Bearer {token}

Result: If successful, the customer is successfully subscribed to the service.

Step 4 — Unsubscribe GET

Cancel the customer's subscription.

https://api.airpay.mobi/api/v2/ext/wap/XL/{service}/unsubscribe?apikey=YOUR_API_KEY&msisdn={msisdn}

Headers: apikey: {apiKey} · Authorization: Bearer {token}

Result: The customer's subscription to the service is cancelled.

5. Important Notes

• The Bearer token expires every 1 hour. Once expired, call Request Token again.
• username = merchant client id, password = merchant client secret.
• Request Token uses Basic Auth with Base64 encoding (format username:password).
• All endpoints except Request Token must include the Authorization: Bearer <token> header and the apikey header.
• Values inside curly braces { } (e.g. {service}, {clickid}, {msisdn}, {otpKey}, {otpValue}) must be replaced with actual values.
• The OTP code is delivered via SMS from sender/SDC 99876; that value is used as otp_value in the Confirm OTP step.
• The apikey and client secret are confidential — do not share them with unauthorized parties.

This API will be used for telco providers that have a subscription process. If a customer wants to unsubscribe from a service, this API will be used. This process applies only to services that implement a subscription model.

Sample request :

curl -X GET "{domain}/api/v1/ext/{CHANNEL}/{TELCO}/{SERVICE}/unsubscribe?apikey={APIKEY}&msisdn={MSISDN}"

Note: API request is made over HTTP(S).

Whenever users initiate an MO request from their mobile phone, the Messaging Platform will forward the request to the content provider's URL using GET method.

The basic format of a MO request for REG is shown below:

https://{{domain}}/mo?event=MOREG&operator={operator}&sdc={shortcode}&msisdn={msisdn}&service={service}&trx_id={{trxid}}&trx_date={trxdate}&click_id={clickid}

The basic format of a MO request for UNREG is shown below:

https://{{domain}}/mo?event=MOUNREG&operator={operator}&sdc={shortcode}&msisdn={msisdn}&service={service}&trx_id={trxid}&trx_date={trxdate}

Note: API request is made over HTTP(S).

Delivery Notifications (DN) indicate whether a message was delivered and charged to the user's handset. Unsuccessful attempts return a negative acknowledgment (FAIL).

HTTP Request for DN Status: Messaging Platform forwards DN requests from the network operator to the content provider's URL using the GET method. Ensure the CP firewall allows access from Messaging Platform IP.

The basic format of an DN First Purchase (FP) is shown below:

https://{{domain}}/dn?event=FP&operator={operator}&sdc={SHORTCODE}&msisdn={MSISDN}&service={SERVICE}&trx_id={TRXID}&trx_date={TRXDATE}&click_id={CLICKID}&status={STATUS}&status_desc={STATUS_DESC}

The basic format of an DN Renewal is shown below:

https://{{domain}}/dn?event=RENEWAL&operator={operator}&sdc={shortcode}&msisdn={msisdn}&service={service}&trx_id={trxid}&trx_date={trxdate}&status={status}&status_desc={status_desc}

Note: API request is made over HTTP(S).

Error Code List: