The Direct Carrier Billing (DCB) HTTP API allows authorized customers (Service Providers) to charge mobile users directly through their mobile phone balance (prepaid) or postpaid billing account when they purchase digital content or subscription-based services. This enables users to complete payments easily without using credit cards or e-wallets—simply by confirming the transaction through their mobile number.
It is strongly recommended to integrate the API in alignment with the Service Program documentation provided by the Airpay technical team during the service setup process to ensure compliance with telco requirements and smooth end-to-end operation.
Airpay Integration API - Thailand
This document specifies the protocols operated between Airpay PLATFORM and the content provider or merchant system.
The protocols explained in the document are for both Mobile Originating (MO) and Mobile Terminating (MT) messages. The global standard used in the communication between two different systems over the Internet using the Hypertext Transport Protocol (HTTP).
Subcription 2 click flow plus (AIS Gaming)
Subscription MSISDN Autofill + OTP Flow
Note: Header Enrichment will no longer provided by telcos, MSISDN will be autofill during subscription process, in case end user, using telco network while process subscription.
Subscription SMS Flow
Note: Every telco has different rules about MT SMS. Process charging will be sent in allowed time as telco policy.
This flow only provided to specific merchant.
Unsubscription Flow
Telco service aggregator will provide following API for specific operator, named API Regular Subscription
Please note that the API's will only provided to each operator based on prior agreements.
Telco service aggregator will generate a token valid for 24 hours.
Telco service aggregator will provide a function to delete expired tokens, running as a background process. It runs daily at 5 AM.
For testing you can use online tools, such as AES Encryption-Decryption.
Summary
Landing page is aims to enhance the user experience by providing a more streamlined flow, a visually appealing interface, and better usability. This landing page integration is also carried out to meet the policy requirements of telecom operators partnering with the service provider.
MT Procedure
Procedure MT Charging:
1. User subscribed via merchant
• The user initiates a subscription on the merchant’s platform (e.g., through portal, web, etc)
• The merchant will calls the Subscription API provided by Airpay (Click Multimedia).
• The API returns a success response if the subscription is valid
2. Airpay (Click Multimedia) stores Subscription Data
• Upon a successful response, the Airpay (Click Multimedia) logs the user data example:
msisdn (encrypted user phone number depends on telco)
trx_id (Transaction ID)
trx_date (Transaction date)
service (Service name)
sdc (Shortcode)
• This data is stored in the airpay’s internal subscription database.
3. Charging and MT Message initiated by Airpay (Click Multimedia)
• The merchant schedules the charging logic (e.g., daily, weekly).
• At the scheduled time, the Airpay (Click Multimedia) sends a charging request to telco and telco will handle the charging
• Upon successful charging, an MT message (Mobile Terminated SMS) will sent to the user confirming the charge.
4. Subscription Renewal
• Renewal is managed by the Airpay (Click Multimedia)
• A scheduled job or background task checks for active subscriptions and triggers the renewal charge based on the cycle (e.g., every 24 hours).
• The system does not make any calls to the airpay (Click multimedia) unless explicitly required for validation or synchronization purposes Unsubscription Handling
5. If the user chooses to unsubscribe:
• The airpay (Click Multimedia) will disables further renewals and charges.
• The airpay (Click multimedia) will send an MT SMS to confirm unsubscription.
• And The airpay will update the user status and send status info to merchant too
Note:
The default MT distribution timeline is set between 7.00hrs - 18.00hrs (GMT+7). If the configuration is scheduled outside of this timeframe, our system will automatically send email reminders or alerts to prompt the responsible parties to provide the correct unique content URL/text and to adjust the timing for MT pushes accordingly.
API Subscription (Auto Filled MSISDN + OTP & 2 Click flow (Gaming))
This API will be used by telco who needed redirect url to merchant's subscription page and will be continue to confirmation page for finishing subscription flow
CURL -X GET “{domain}/api/v1/ext/{channel}/{telco}/{service}/subscribe?apikey={apikey}&clickid={clickid}”
Authorizations:
path Parameters
| channel required | string <= 50 characters Channel name (Type of delivery channel: sms and wap) |
| telco required | string <= 150 characters Telco masking code |
| service required | string <= 50 characters Service id |
query Parameters
| apikey required | string <= 150 characters API key |
| clickid required | string <= 150 characters Tracking ID for campaign tracking |
| trxid | string <= 50 characters Transaction ID |
| msisdn | string <= 50 characters The phone number of the user/sender (MSISDN will be encrypted) |
Responses
Response samples
- 200
{- "code": 200,
- "message": "success",
}This section provides a comprehensive list of error codes and their corresponding descriptions.
| Error Code | Error Message |
|---|---|
| 400 | Bad request |
| 500 | Internal system error |
| 900 | Invalid signature |
| 901 | Invalid token |
| 902 | Token expired |
| 903 | Invalid channel |
| 904 | Invalid telco |
| 905 | Invalid service id |
| 906 | Invalid msisdn |
| 907 | Invalid OTP |
| 9071 | Invalid OTP key, not found or expired |
| 9072 | Invalid OTP value or not found |
| 908 | Channel not active |
| 909 | Telco not active |
| 910 | Service id not active |
| 911 | Duplicate trxid |
| 912 | Invalid Source or source may not register to this service |
DCB Airpay Account Creation
Requirement: Valid Email Address
Note: After admin verification, merchant will be provided with login credentials to Airpay messaging platform at http://merchant.airpay.mobi/
Service Data Availability
Following the creation of the Airpay account, partners can navigate to the "Report/Reporting Details" section in the navigation bar. This area will display all relevant service data once the service integration has been successfully completed as shown in Figure below:
Provisioning Of Integration Urls
MO Url: Reply URL at CP Server (If Applicable) for receiving HTTP MO
Example. 1) http://partner.com/mo
Example. 2) http://partner.com/mobile-originating
Example. 3) https://203.208.172.216:8080/airpay/mo
DN URL: Reply URL at CP Server (If Applicable) for Receiving DN
Example. 1) http://partner.com/dn
Example. 2) http://partner.com/delivery-notification
Example. 3) https://203.208.172.216:8080/airpay/dn
Note: Each merchant is required to provide only one MO (Mobile Originated) and one DN (Delivery Notification) URL. The furnished URLs should be intended for production purposes.
We expected the merchant to send a response “OK” when the process is success
Sample:
https://{{domain}}/mo?event=MOREG&operator={operator}&sdc={shortcode}&msisdn={msisdn}&service={service}&trx_id={trxid}&trx_date={trxdate}, Response: OK, Status: 200 OK, Status Code: 200,
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}, Response:OK , Status: 200 OK, Status Code: 200,
MO HTTP Interface
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. Please note that CP firewall must be opened to allow the access of LINKIT360/Click Multimedia IP to MO receive any messages from MESSAGING PLATFORM.
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}
Authorizations:
query Parameters
| operator required | string Operator name |
| event required | string <= 50 characters Enum: "MOREG" "MOUNREG" Action type indicating the type of MO request. MOREG: MO for Subscription MOUNREG: MO for Unsubscription |
| sdc required | string <= 50 characters sdc is the 5-digits number that the user send request to |
| msisdn required | string <= 50 characters The phone number of the user/sender (MSISDN will be encrypted) |
| service required | string <= 50 characters The service name |
| trx_id required | string <= 50 characters Transaction ID |
| trx_date required | string <date-time> <= 50 characters Transaction Date format YYYY-MM-DDTHH:MM:SS±HH:MM |
| click_id required | string <= 150 characters Tracking ID for campaign tracking |
Delivery Notification
Delivery Notifications are message acknowledgments returned from the network operator to MESSAGING PLATFORM. It is used to indicate the MT delivered and charged to user's handset or not. For unsuccessful delivery attempts, MESSAGING PLATFORM will return a negative acknowledgment (FAIL) outlining the failure reason.
HTTP Request for DN Status: MESSAGING PLATFORM will forward the DN request to the content provider's URL using GET method.
The basic format of a 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 a 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}
The basic format of a DN Retry FP is shown below:
https://{{domain}}/dn?event=RETRYFP&operator={operator}&sdc={shortcode}&msisdn={msisdn}&service={service}&trx_id={trxid}&trx_date={trxdate}&status={status}&status_desc={status_desc}
The basic format of a Purge is shown below:
https://{{domain}}/dn/?event=PURGE&operator={operator}&sdc={shortcode}&msisdn={msisdn}&service={service}&trx_id={trxid}&trx_date={trxdate}
Error Code List:
| Error Code | Description | Note |
|---|---|---|
| 0 | Failed | |
| 1 | Success | |
| 2 | Unknown reason | |
| 600 | Insufficient balance / not enough credit | Checking Parameter |
| 601 | MSISDN in grace period | Checking Parameter |
| 602 | MSISDN blacklisted | Checking Parameter |
| 603 | User doesn’t exist | Checking Parameter |
| 604 | MSISDN purged | Checking Parameter |
| 605 | Timeout charging | Checking Parameter |
| 606 | Message is too long | Checking Parameter |
| 607 | Mandatory parameter is missing | Checking Parameter |
| 608 | User is in quarantine | Checking Parameter |
| 609 | Invalid recipient | Checking Parameter |
| 610 | Charging failed from telco gateway | Checking Parameter |
| 611 | Invalid shortcode | Checking Parameter |
| 612 | Throttling error | Checking Parameter |
| 613 | User status subscription is abnormal | Checking Parameter |
| 614 | Storage partition is full | Checking Parameter |
| 615 | Authentication is failed | Checking Parameter |
| 616 | TRX ID format rejected | Checking Parameter |
| 617 | Multiple charge is not allowed, and TRX ID provided by CP | Checking Parameter |
| 618 | Subscription quota is finished | Checking Parameter |
| 619 | Invalid TRX ID | Checking Parameter |
| 620 | Charging failed from telco billing | Checking Parameter |
| 621 | Error format request charging | Checking Parameter |
| 622 | Unspecified error | Checking Parameter |
| 623 | Unauthorized | Checking Parameter |
| 624 | Not found | Checking Parameter |
| 625 | Subscription error | Checking Parameter |
| 626 | MSISDN is not active | Checking Parameter |
| 627 | Invalid subscription | Checking Parameter |
| 628 | Content provider not found | Checking Parameter |
| 629 | Service not found | Checking Parameter |
| 630 | Service status is not active | Checking Parameter |
| 631 | Cannot subscribe the service | Checking Parameter |
| 632 | Wrong network | Checking Parameter |
| 633 | Mobile is Block list | Checking Parameter |
| 634 | Content delivery error | Checking Parameter |
| 635 | Delivery to phone failed | Checking Parameter |
| 636 | Unknown Subscriber | Checking Parameter |
| 637 | Subscriber error | Checking Parameter |
| 638 | Mobile switch off | Checking Parameter |
| 639 | Mobile error | Checking Parameter |
| 640 | Invalid service | Checking Parameter |
| 641 | Generic catch all Charging Failed from SOA | Checking Parameter |
| 642 | Generic catch all charging failed from BPGW | Checking Parameter |
| 999 | Default error code | Checking Parameter |
Authorizations:
query Parameters
| operator required | string Operator name |
| event required | string <= 50 characters Enum: "FP" "RENEWAL" "RETRYFP" "PURGE" Action type indicating the type of delivery notification. FP: Notification for First Purchase RENEWAL: Notification for Renewal RETRYFP: Notification for retry first purchase PURGE: Notification for Purge |
| sdc required | string <= 50 characters sdc is the 5-digits number that the user send request to |
| msisdn required | string <= 50 characters The phone number of the user/sender (MSISDN will be encrypted) |
| service required | string <= 50 characters The service name |
| trx_id required | string <= 150 characters Transaction ID |
| trx_date required | string <date-time> <= 50 characters Transaction Date format YYYY-MM-DDTHH:MM:SS±HH:MM |
| click_id required | string <= 150 characters Tracking ID for campaign tracking |
| status required | string <= 5 characters Status code |
| status_desc required | string <= 50 characters Description detail of status |
