Developer Documentations

Info

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

Syntornization

userStatusChange URL	Please Request
userStatusSync	Please Request
Notify URL	Please Request

userStatusChange

UserStatusChange Request

HTTP Method POST

Operation Used by Telco Operator to sub/unsub a user in the merchant side

curl --location --request POST 'https://[Merchant Endpoint]' \
--header 'Content-Type: application/json' \
--header 'apikey: {APIKey}' \
--header 'HTTP_MSISDN: 9641234567890' \
--data-raw '{
  "requestId":"8635081281569934573",
  "userId":"964123456789",
  "action":"subscribe",
  "product":"[Product]",
  "productId":"[Product]",
  "channel":"CC"
}'

Header Parameters

Name	Description	Required
AuthCode	authentication key sent from Merchant side

Request Parameters

A unique identifier of the charge

Name	Type	Description	Required
requestId	String	Transaction generated by [MERCHANTNAME]. It should be preceded by the [merchantCode] as prefix.
userId	String	Countrycode + MSISDN of the user
action	String	subscribe = subscribe the user and grant service access. unsubscribe = the service will remain active until the end of the current subscription cycle.
Channel	String	The channel of action, it can be: MobileApp or CC
product	String	Identifier of the product, in our case “[productName]”
productId	String	The identifier of the product on Telco operator side.

Response

Merchant should acknowledge the request followed by notify request.

On success, Merchant should send back HTTP 200 with the subscriptionId created after sync request with action subscribe. Any other HTTP status will be treated as error.

Response 1

{
  "status": "1",
  "statusDetail": "Successful Operation."
}

Response 2

{
  "status": "-308",
  "statusDetail": "Unknown error."
}

Response Parameters

Name	Type	Description	Required
status	String	“1” if successful operation. “ERROR_CODE” in case of fail.
statusDetail	String	Represents the description of the request: “Successful Operation” in case of success, “ERROR_DESCRIPTION” in case of fail.

userStatusSync

Request

UserStatusSync Request

HTTP Method POST

Operation Used by Telco Operator that manage the user life cycle to synchronize the user status with the merchant.

curl --location --request POST 'https://[Merchant Endpoint]' \
--header 'Content-Type: application/json' \
--header 'apikey: {APIKey}' \
--header 'HTTP_MSISDN: 9641234567890' \
--data-raw '{
  "userId":"96412345678",
  "action":"subscribe",
  "opcoServiceId":"123310169",
  "opcoProduct":"101633239",
  "opcosubProduct":"[subProductName]",
  "opcoTransactionId":"035288953320233",
  "freeOfCharge":"true",
  "channelId":"2"
}'

curl --location --request POST 'https://[Merchant Endpoint]' \
--header 'Content-Type: application/json' \
--header 'apikey: {APIKey}' \
--header 'HTTP_MSISDN: 9641234567890' \
--data-raw '{
  "userId":"96412345678",
  "action":"unsubscribe",
  "opcoServiceId":"123310169",
  "opcoProduct":"101633239",
  "opcosubProduct":"[subProductName]",
  "opcoTransactionId":"035288953320233",
  "channelId":"2"
}'

curl --location --request POST 'https://[Dizlee API Endpoint]' \
--header 'Content-Type: application/json' \
--header 'apikey: {APIKey}' \
--header 'HTTP_MSISDN: 9641234567890' \
--data-raw '{
  "userId":"96412345678",
  "action":"update",
  "opcoServiceId":"123310169",
  "opcoProduct":"101633239",
  "opcosubProduct":"[subProductName]",
  "opcoTransactionId":"035288953320233",
  "statusChange":"activate",
  "channelId":"99"
}'

Header Parameters

Name	Description	Required
authCode	authentication key sent from Merchant side

Request Parameters

Name	Type	Description	Required
userId	String	Countrycode + MSISDN of the user
action	String	subscribe, unsubscribe, or update
opcoServiceId	String	Operator defined value
opcoProduct	String	Operator defined value
opcoSubProduct	String	Identifier of the subproduct in case there are multiple subproduct types under the same product.
opcoTransactionId	String	Operator defined value
statusChange	String	Only present in case of action=update: activate or deactivate
freeOfCharge	boolean	true or false. Only present in case of action=subscribe. This parameter is received only when the user is in the free trial.
channelId	String	Operation channel. 1: web, 2: SMS, 102: CC Portal, 99: Other

Notify

Request

Notify - Request

HTTP Method POST

Operation Used by merchant to notify Dizlee by the user action (Subscription, Unsubscription, etc.)

curl --location --request POST 'https://[Dizlee API Endpoint]' \
--header 'Content-Type: application/json' \
--header 'apikey: {APIKey}' \
--header 'HTTP_MSISDN: 9641234567890' \
--data-raw '{
  "notifyRequestId":"8635081281569934573",
  "subscriptionId":"8635081281569934573",
  "userId":"964123456789",
  "aggregatorId":"[aggregatorName]",
  "merchantId":"[merchantName]",
  "product":"[Product]",
  "subProduct":"[subProduct]",
  "type":"subscribe",
  "channel":"WEB"
}'

curl --location --request POST 'https://[Dizlee API Endpoint]' \
--header 'Content-Type: application/json' \
--header 'apikey: {APIKey}' \
--header 'HTTP_MSISDN: 9641234567890' \
--data-raw '{
  "notifyRequestId":"8635081281569934573",
  "subscriptionId":"8635081281569934573",
  "correlationId":"31564865456",
  "userId":"964123456789",
  "aggregatorId":"[aggregatorName]",
  "merchantId":"[merchantName]",
  "product":"[Product]",
  "subProduct":"[subProduct]",
  "type":"FlaggedToUnsub",
  "status":"success",
  "channel":"WEB",
  "productId":"9619",
  "revokingServiceDate":"05-03-2021 10:00:00"
}'

curl --location --request POST 'https://[Dizlee API Endpoint]' \
--header 'Content-Type: application/json' \
--header 'apikey: {APIKey}' \
--header 'HTTP_MSISDN: 9641234567890' \
--data-raw '{
  "notifyRequestId":"8635081281569934573",
  "subscriptionId":"8635081281569934573",
  "correlationId":"31564865456",
  "userId":"964123456789",
  "aggregatorId":"[aggregatorName]",
  "merchantId":"[merchantName]",
  "product":"[Product]",
  "subProduct":"[subProduct]",
  "type":"Subscribe",
  "status":"failure",
  "channel":"WEB",
  "productId":"9619",
  "failReason":"insufficient balance",
  "failErrorCode":"-304"
}'

Header Parameter

Name	Description	Required
apikey	authentication key sent from Dizlee side
HTTP_MSISDN	mobile phone number in international format

Request Parameter

Name	Type	Description	Required
notifyRequestId	String	A unique identifier of the charge transaction generated by [MERCHANTNAME]. It should be preceded by the [merchantCode] as prefix.
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.
userId	String	Countrycode + MSISDN of the user
aggregatorId	String	The northbound aggregator partner
merchantId	String	The Owner of the product. [MERCHANTNAME] in our case
product	String	Identifier of the product, in our case “[productName]”
subProduct	String	Identifier of the subproduct in case there are multiple subproduct types under the same product.
productId	String	Identifier of the product
correlationId	String	Should contain the requestId received in the userStatusChange request. It can be empty for subscriptions done through the web channel.
failReason	String	If the status is failure, this should contain the failure cause.
failErroCode	String	If the status is failure, this should contain the failure error code.
revokingServiceDate	String	If the type is FlaggedToUnsub, this should contain the date of revoking the user access to the service.

Response Codes

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
-308	Unknown error from Opco	Unknown error.
-311	Bad MSISDN	User not found.
-322	Quota limit Exceeded	Quota limit Exceeded
-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