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 - Philippines
This document specifies the protocols operated between SMSGW MESSAGING PLATFORM and the content provider 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).
Telco service aggregator will provide API for Redirection telco page.
Please note that the APIs will only be provided to each operator based on prior agreements.
Telco service aggregator will generate a token valid for 24 hours.
Subscription Flow
Click2SMS
This API will be used by merchant who needed redirect url to Telco’s subscription page and will be continue to confirmation page for finishing subscription flow
Sample request :
CURL -X GET {domain}/api/v1/ext/{channel}/{telco}/{service}/subscribe?apikey={apikey}&clickid={clickid}
Note: API request is made over HTTP(S).
Authorizations:
path Parameters
| channel required | string <= 50 characters Channel name |
| telco required | string <= 150 characters Telco masking code |
| service required | string <= 50 characters Service |
query Parameters
| apikey required | string <= 150 characters API key |
| clickid required | string <= 50 characters Tracking ID for campaign |
Responses
Response samples
- 200
{- "code": 200,
- "message": "success",
}This section provides a comprehensive list of error codes and their corresponding descriptions that may be encountered during API interactions.
| Code | 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 2
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}
Note: API request is made over HTTP(S).
Authorizations:
query Parameters
| operator required | string <= 50 characters Operator name |
| click_id required | string <= 50 characters Tracking ID for campaign |
| 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 Short code that the user send request to |
| msisdn required | string <= 50 characters The phone number of the user/sender (encrypted depending Geo and Service) |
| service required | string <= 50 characters The service name |
| trx_id required | string <= 150 characters Transaction ID from LINKIT360 |
| trx_date required | string <date-time> <= 50 characters Transaction Date format YYYY-MM-DDTHH:MM:SS±HH:MM |
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. When delivering messages through our network. For unsuccessful delivery attempts, MESSAGING PLATFORM will return a negative acknowledgment (FAIL) outlining the failure reason.
Whenever MESSAGING PLATFORM obtain a DN request from network operator, the gateway 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 MESSAGING PLATFORM IP to receive any DN messages from MESSAGING PLATFORM.
The basic format of an DN First Purchase (FP) is shown below:
https://domain/notification?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/notification?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:
| 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 <= 50 characters Operator name |
| click_id required | string <= 50 characters Tracking ID for campaign |
| event required | string <= 50 characters Enum: "FP" "RENEWAL" Action type indicating the type of delivery notification. FP: Notification for First Purchase RENEWAL: Notification for Renewal |
| sdc required | string <= 50 characters Short code that the user send request to |
| msisdn required | string <= 50 characters The phone number of the user/sender (encrypted depending Geo and Service) |
| service required | string <= 50 characters The service name |
| trx_id required | string <= 150 characters Transaction ID from LINKIT360 |
| trx_date required | string <date-time> <= 50 characters Transaction Date format YYYY-MM-DDTHH:MM:SS±HH:MM |
| status required | string <= 50 characters Status code |
| status_desc required | string <= 50 characters Description detail of status |