Developer Documentations

Charging & Messaging API
2
3

Dizlee Charging API Specification

All APIs discussed under this section are RESTful APIs with a JSON payload where applicable. All Inbound and Outbound requests must use secure connection (https).

API End Point Name URI
Charging (SP)
Charge URL Please Request
Refund URL Please Request

Charging (SP)

HTTP Method POST
Operation Used by merchant to charge the user

Request

curl –location –request POST ‘https://[Dizlee API Endpoint]’ \

–header ‘Content-Type: application/json’ \

–header ‘apikey: {APIKey}’ \

–header ‘HTTP_MSISDN: 9641234567890’ \

–data-raw ‘{ “chargeRequestId”:”8635081281569934573″, “subscriptionId”:”SP”, “userId”:”964123456789″,

“type”:”SinglePurchase”, “firstCharge”:true, “amount”:0.001,

“currency”:”IQD”, “totalCharge_p30d”:0, “aggregatorId”:”[aggregatorName]”, “merchantId”:”[merchantName]”, “product”:”[Product]”, “subProduct”:”[subProduct]”, “channel”:”WEB”, “promoter”:”[Merchant or Telco]”

}’

Header Parameters

Name Description Required
apikey authentication key sent from Dizlee side Y
HTTP_MSISDN

mobile phone number in international

format

 Y

Request Parameters 

Name Type Description Required
chargeRequestId String

A unique identifier of the charge

Transaction generated by [MERCHANTNAME]. It should be preceded by the [merchantCode] as

prefix.

 Y
subscriptionId String

A unique identifier that represents the user lifecycle since subscription.

It should be preceded by [merchantCode] as prefix.

subscriptionId should be “SP” for onetime payment.

 Y
userId String Countrycode + MSISDN of the user Y
type String The type of the Charge request it can be: “SinglePurchase” (one time purchase) Y
firstCharge Boolean

Value:

– true: first successful charging event (amount>0) or in case of Single Puchase charges

 Y
amount Decimal Charge amount Y
currency String

The currency code. For example “KWD” (ISO-4217

Code)

 Y
totalCharge_p30d Decimal Sum of total charge in the last 30 days Y
aggregatorId String The northbound aggregator partner Y
merchantId String

The Owner of the product. [MERCHANTNAME] in

our case

 Y
product String

Identifier of the product, in our case

“[productName]”

 Y
subProduct String

Identifier of the subproduct in case if there are multiple subproducts types under the same

product.

 Y
channel String The channel of subscription, it can be one of the following: WEB, SMS, MobileApp or CC Y
promoter String

Specifies the promoter of the campaign

Can be [Merchant] or [Telco Operator]

 Y
vatAmount int

The tax value:

For Prepaid: it will contains the tax value For postpaid: it will be 0

Mandatory for some Telco Operator

 O
billingType String

billingType should be extracted from the getProfile response.

can be: [Postpaid, Prepaid]

 O

 

    Mandatory for some Telco Operator  
profileRequestId String

profileRequestId should be the request Id used in the getprofile to retrieve the billingType.

Mandatory for some Telco Operator

 O
SID String

The service ID (Will be provided by Dizlee)

Mandatory for some Telco Operator

 O
PID String

The Product ID (Will be provided by Dizlee)

Mandatory for some Telco Operator

 O

  

Response 1

{
“status”: “1”,
“statusDetail”: ” Successful Operation.”
} 

Response 2

{
“status” : “1”,
“statusDetail” : “Successful Operation.”, “chargeResponseId” : “29320”
}

Response 3

{
“status”: “-304”,
“statusDetail”: “Operation Failed. Insufficient Funds.”, “chargeResponseId”: “-1”
}

Response Parameters

Name Type Description Required
status String

–          “1” if successful Operation

–          “ERROR_CODE” in case of fail

 Y
statusDetail String

Represent the description of the request

–          “Successful Operation” in case of Success

–          “ERROR_DESCRIPTION” in case of Fail

 Y
chargeResponseId String

This is Telco OPCO generated identification of the Charge Response operation.

Can be used within the refund request (if refund requires OPCO chargeId)

 O

Refund 

HTTP Method POST
Operation Used by Merchant to refund the user

 

Request

curl –location –request POST ‘https://[Dizlee API Endpoint]’ \
–header ‘Content-Type: application/json’ \
–header ‘apikey: {APIKey}’ \
–header ‘HTTP_MSISDN: 9641234567890’ \
–data-raw ‘{ “refundRequestId”:”DVO00003b26b140600ce5cc9296″, “subscriptionId”: “SP”, “transactionId”:”8635081281569934573″, “chargeId”:”8635081281569934573″, “userId”:”964123456789″,
“amount”:0.001,
“currency”:”IQD”, “aggregatorId”:”[aggregatorName]”, “merchantId”:”[merchantName]”, “product”:”[Product]”, “subProduct”:”[subProduct]”, “reason”:”test”,
“purpose”:”[Purpose]”
}’

Header Parameters

Name Description Required
apikey authentication key sent from Dizlee side Y
HTTP_MSISDN

mobile phone number in international

format

 Y

 

Request Parameters

Name Type Description Required
refundRequestId String

A unique identifier of the refund

Transaction generated by [merchantName]. It should be preceded by the [merchantCode] as prefix.

 Y
subscriptionId String

A unique identifier that represents the user lifecycle since subscription.

Should be “SP” for onetime payment.

 Y
userId String Countrycode + MSISDN of the user Y
transactionId String The identifier of the transaction to be refunded, generated by the Merchant in the earlier purchase request. It should be preceded by the [merchantCode] as prefix. Y

 

 

chargeResponseId String

Received from some Telco Operator in Charge Requests

This is OPCO generated identification of the Charge Response operation.

Can be used within the refund request (if refund requires OPCO chargeId)

 O
amount Decimal

Amount to be refunded, it must be less or equal than the total amount pending to refund on the original transaction.

If not filled, the full amount is refunded

 Y
currency String The currency code. For example “KWD” Y
aggregatorId String The northbound aggregator partner Y
merchantId String

The Owner of the product. [MERCHANTNAME] in

our case

 Y
product String

Identifier of the product, in our case

“[productName]”

 Y
subProduct String

Identifier of the subproduct in case if there are

multiple subproducts types under the same product.

 Y
reason String The refund reason Y
purpose String Should be as [merchantName]-[ productName] Y

 

Response 1

{
“status”: “1”,
“statusDetail”: ” Successful Operation.”
} 

Response 2

{
“status”: “1”,
“statusDetail”: “Unknown Error.”
}

Response Parameters

Name Type Description Required
status String

–          “1” if successful Operation

–          “ERROR_CODE” in case of fail

 Y
statusDetail String

Represent the description of the request

–          “Successful Operation” in case of Success

–          “ERROR_DESCRIPTION” in case of Fail

 Y

Response Codes – Charging API  

CODE TYPE DESCRIPTION
1 OK Successful Operation
-100 Missing param/value Missing param/value
-101 Authentication error You are not authorized to perform this request
-200 Cannot perform action Unable to perform action.
-300 Account Inactive Operation Failed.Account Inactive
-301 Single Charge Failed Operation Failed,Single Charge Failed
-302 DOB is not allowed for the user Operation Failed. Subscription Failed.
-304 Insufficient Funds Operation Failed.Insufficient Funds
-305 Duplicate Transaction Operation Failed.Duplicate Transaction
-306 User status changed to not allowed for DOB during the renewal process Operation Failed. Remove Subscription.
-307 Suspend Service Operation Failed.Suspend Service
-308 Unknown error from Opco Unknown error.
-311 Bad MSISDN User not found.
-317 Charge – subscription – failed User is not eligible
-318 Charge failed Past 30 days charge limit exceeded
-319 Refund Failed Operation Failed. Charge transaction not found.
-320 Refund – Failed Operation Failed. Charge transaction already refunded
-322 Quota limit Exceeded Quota limit Exceeded
-323 Insufficient Funds Operation Failed.Insufficient Funds
-324 Charge / Eligibility failed User is not eligible – Inactive Status
-325 Charge / Eligibility failed User is not eligible – Has Stop SLA Service
-326 Charge / Eligibility failed User is not eligible – Corporate Customer
-327 Refund Failed Operation Failed. Refund rejected.
-330 Operation Failed Operation Failed. Service Not Found.
-331 Operation Failed Operation Failed. Product Not Found.
-332 Incorrect eligibility ResponseId or transactionId Transactionid is incorrect or has expired
-333 Subscription is not allowed from this Channel Subscription is not allowed from this Channel
-429 Too Many Requests Requests rate limit reached, please contact support
-500 Internal Error Something went wrong.
-504 Timeout occurred on Opco side Gateway Timeout

 

Dizlee API Specification – Messaging

NOTE:

All APIs discussed under this section are RESTful APIs with a JSON payload where applicable.

API End Point Name URI
Messaging
SMSMT URL Please Request
SMSMO URL To Be Provided by Merchant

SendSMS (SMSMT)

HTTP Method POST
Operation Used by merchant to send information messages to the user

Request

curl –location –request POST ‘https://[Dizlee API Endpoint]’ \
–header ‘Content-Type: application/json’ \
–header ‘apikey: {APIKey}’ \
–header ‘HTTP_MSISDN: 9641234567890’ \
–data-raw ‘{
“smsRequestId”:” [merchantCode]00003b26b140600ce5cc9296″, “subscriptionId”:” [merchantCode]00003b26b140600ce5cc9296″, “sender”: “[senderId]”,
“receiver”: ” 9641234567890 “,
“language”: “En”, “msgBody”: “Test Message”,
“aggregatorId”:” [merchantName]”, “merchantId”:” [merchantName]”, “product”: ” [productName] “, “subProduct”:” [subProductName] “
}’

Header Parameters

Name Description Required
apikey authentication key sent from Dizlee side Y
HTTP_MSISDN

mobile phone number in international

format

Y

 

Request Parameters

Name Type Description Required
smsRequestId String

A unique identifier of the sendSMS

Transaction generated by [merchantName].It should be preceded by [merchantCode] as prefix.

 Y
subscriptionId String

A unique identifier that represents the user lifecycle since subscription. It should be preceded by [merchantCode] as prefix.

Can be empty in the initial Client identification flow – but should be present in later SendSMS calls.

* subscriptionId should be “SP” for onetime payment.

 O
sender String Sender. Can be a short code, long code or text originator Y
receiver String Countrycode + The user’s mobile phone number in international format Y
language String Message language “Ar” for Arabic, “En” for English Y
msgBody String Message body of the MT in UTF-8 encoding Y
aggregatorId String The northbound aggregator partner Y
merchantId String The Ownder of the product. [MERCHANTNAME] in our case Y
product String Identifier of the product, in our case “[productName]” Y
subProduct String Identifier of the subproduct in case if there are multiple subproducts types under the same product. Y
SID String

The Service ID (Will be provided by FOO)

Mandatory in case of Single Purchase Services in KSA and KW flows.

 O
PID String The Product ID (Will be provided by FOO) Mandatory in case of Single Purchase Services in KSA and KW flows. O

Response

{
“status”: “1”,
“statusDetail”: “Sms successfully sent.”
}

Response Parameters

Name Type Description
status String Status code
statusDetail String Free-form status description

SMSMO

HTTP Method POST
Operation Used by Telco Operator to send the user sub/unsub messages to the merchant

Request

curl –location –request POST ‘https://[MerchantEndpoint]’ \
–header ‘authkey: [MerchantAuthKey]’ \
–header ‘Content-Type: application/json’ \
–data-raw ‘{
“Sender”: “9641234567890”,
“Destination”: “[SC]”,
“MessageType”: “1”,
“MessageText”: “014”
}’

Header Parameters

Name Description Required
Authkey authentication key sent from Merchant side Y

Request Parameters

Name Type Description Required
Sender String The MSISDN that sent the SMS. Y
Destination String The Short code/number the SMS was sent to. Y
messageType String

The SMS language. “0” for English and “1” for

Arabic.

 Y
messageText String The content of the SMS. Y

Response

Request Acknowledgement with 200 OK from the merchant

Response Codes – Messaging API

CODE TYPE DESCRIPTION
1 OK Successful Operation
-100 Missing param/value Missing param/value
-101 Authentication error You are not authorized to perform this request
-200 Cannot perform action Unable to perform action.
-303 Sending SMS Failed. Sending SMS Failed.
-308 Unknown error from Opco Unknown error.
-311 Bad MSISDN User not found.
-429 Too Many Requests Requests rate limit reached, please contact support
-500 Internal Error Something went wrong.
-504 Timeout occurred on Opco side Gateway Timeout

© 2025 COPYRIGHT DIZLEE.

Who we are

The most advanced digital monetization ecosystem provider in the MENA region. A one-stop shop for businesses to discover, integrate, and manage APIs.

API Marketplace
Advertising
DCB
Documentation
About

Contact us

info@dizlee.com
+965 2464 4011
Airport Road,
Shuwaikh | Al- Asima,
Kuwait