Reward Token API
API allows application to reward and redeem data, and SMS bundles to/from a users mobile rewards wallet
Content
Authorization API calls
All API call requests to ideabiz.lk require Authorization headers. Please refer (http://docs.ideabiz.lk/Getting_Started/Generate_Token) for Authorization
MSISDN
Eg : 766691500
Method
The following REST methods are available:
- Generate Rewards Token
- Redeem Rewards Token
- Apply Rewards
Generate Rewards Token
Request
Given below is a sample request of Generate Rewards Token.
Resource URL
https://ideabiz.lk/apicall/digitalrewards/v0.1/rewards/data/generate
HTTP Method
POST
Headers
Content-Type : application/json
Authorization: Bearer [access token]
Accept : application/json
Sample Headers
Content-Type : application/json
Authorization: Bearer bc4dcd7bre35rd4a95e6b1f347db93
Accept : application/json
Body
{
"rewardsGenerateRequest":{
"amount":10,
"clientCorrelator":"123456",
"redemptionRequest": {
"notifyURL":"http://rewards-creating-application.com/notifyOfRedemptionURL",
"callbackData":"some-data-useful-to-the-requester"
},
"rewardsTag":"Noodles Promo"}
}
Given below are the Request parameters of Generate Rewards Token.
Parameter name |
Description |
Usage |
amount |
(decimal) the value of the amount parameter will differ based on the {typeOfReward}; sms – The number of SMS data – The amount of data in MB |
Mandatory |
callbackData |
(string) will be passed back in this notification. This is used to identify the tokens generated related to requests (or any other useful data, such as a function name). This is only valid if notifications are required |
Optional |
clientCorrelator |
(string) uniquely identifies this request. |
Mandatory |
notifyURL |
(URI) the URL to which you would like to send the notification of redemption. (Currently cannot call external URL as micro-service server has no internet access) |
Reserved |
rewardsTag |
(string) tag information for the rewards token |
Optional |
Response
Given below is a sample response of Generate Rewards Token.
{
"rewardsGenerateResponse":{
"amount":10,
"pin":"123456789",
"clientCorrelator":"123456",
" redemptionRequest ": {
"notifyURL":"http://rewards-creating-application.com/notifyOfRedemptionURL",
"callbackData":"some-data-useful-to-the-requester"
},
"rewardsTag":"Noodles Promo",
"resourceURL": "http://tokens.com/v1/rewards/data/tokens/abc123"
}
The following are the Response parameters of Generate Rewards Token. All Request parameters will be relayed in the response. Additionally pin and resourceURL parameters will be added to the response.
Parameter name |
Description |
Usage |
amount |
(decimal) the value of the amount parameter will differ based on the {typeOfReward}; sms – The number of SMS data – The amount of data in MB |
Mandatory |
pin |
(numeric) Unique PIN to redeem a generated token. |
Mandatory |
clientCorrelator |
(string) uniquely identifies this request. |
Mandatory |
callbackData |
(string) will be passed back in this notification. This is used to identify the tokens generated related to requests (or any other useful data, such as a function name). This is only valid if notifications are required |
Optional |
notifyURL |
(URI) the URL to which you would like to send the notification of redemption. |
Reserved |
rewardsTag |
(string) tag information for the rewards token |
Optional |
resourceURL |
A reference URL to the request |
Mandatory |
Redeem Rewards Token
Request
Given below is a sample request of Redeem Rewards Token.
Resource URL
https://ideabiz.lk/apicall/digitalrewards/v0.1/rewards/{msisdn}/
Sample URL
https://ideabiz.lk/apicall/digitalrewards/v0.1/rewards/766691500/
HTTP Method
POST
Headers
Content-Type : application/json
Authorization: Bearer [access token]
Accept : application/json
Sample Headers
Content-Type : application/json
Authorization: Bearer bc4dcd7bre35rd4a95e6b1f347db93
Accept : application/json
Body
{
"rewardsRedeemRequest":{
"pin":"634304281914",
"clientCorrelator":"123456",
"redemptionRequest":
{
"notifyURL":"http://rewards-creating-application.com/notifyOfRedemptionURL",
"callbackData":"some-data-useful-to-the-requester"
}
}
}
Given below are the Request parameters of Redeem Rewards Token.
Parameter name |
Description |
Usage |
msisdn |
Mobile number of the subscriber. |
Mandatory |
pin |
(numeric) Unique PIN to redeem a generated token. |
Mandatory |
clientCorrelator |
(string) uniquely identifies this request. If there is a communication failure during the request, by using the same clientCorrelator, it will avoid creating the same reward twice when retrying the request. |
Mandatory |
notifyURL |
(URI) the URL to which you would like to send the notification of redemption. |
Reserved |
callbackData |
(string) will be passed back in this notification. This is used to identify the tokens generated related to requests (or any other useful data, such as a function name). This is only valid if notifications are required |
Optional |
Response
Given below is a sample response of Redeem Rewards Token.
{
"rewardsRedeemResponse": {
"pin": "472110542908",
"amount": 100,
"type": "data",
"clientCorrelator": "123456",
"redemptionResponse": {
"notifyURL": "http://rewards-creating-application.com/notifyOfRedemptionURL",
"callbackData": "some-data-useful-to-the-requester"
},
"resourceURL": "http://10.62.160.154:8080/v0.1/rewards/777334035/redeem"
}
}
The following are the Response parameters of Redeem Rewards Token. All request parameters will be relayed in the response. Additionally type and resourceURL parameters will be added to the response.
Parameter name |
Description |
Usage |
amount |
(decimal) the value of the amount parameter will differ based on the {type}; sms – The number of SMS data – The amount of data in MB |
Mandatory |
type |
(string) the type of reward, if its sms or data. |
Mandatory |
pin |
(numeric) Unique PIN to redeem a generated token. |
Mandatory |
clientCorrelator |
(string) uniquely identifies this request. |
Mandatory |
callbackData |
(string) will be passed back in this notification. This is used to identify the tokens generated related to requests (or any other useful data, such as a function name). This is only valid if notifications are required. |
Optional |
notifyURL |
(URI) the URL to which you would like to send the notification of redemption. |
Reserved |
resourceURL |
A reference URL to the request. |
Mandatory |
Apply Rewards
Request
Given below is a sample request of Apply Rewards.
Resource URL
https://ideabiz.lk/apicall/digitalrewards/v0.1/rewards/{msisdn}/apply
Sample URL
https://ideabiz.lk/apicall/digitalrewards/v0.1/rewards/766691500/apply
HTTP Method
POST
Headers
Content-Type : application/json
Authorization: Bearer [access token]
Accept : application/json
Sample Headers
Content-Type : application/json
Authorization: Bearer bc4dcd7bre35rd4a95e6b1f347db93
Accept : application/json
Body
{
"rewardsApplyRequest": {
"type": "data",
"amount": 1,
"clientCorrelator": "123458",
"redemptionRequest": {
"notifyURL": "http://rewards-creating-application.com/notifyOfRedemptionURL",
"callbackData": "some-data-useful-to-the-requester"
},
"rewardsTag":"ABC",
"smsText": "You have been awareded 1MB"
}
}
The following are the Request parameters of Apply Rewards.
Parameter name |
Description |
Usage |
msisdn |
Mobile number of the subscriber. |
Mandatory |
type |
(string) the type of reward, if its sms or data. |
Mandatory |
Amount |
(decimal) the value of the amount parameter will differ based on the {type}; sms – The number of SMS data – The amount of data in MB |
Mandatory |
clientCorrelator |
(string) uniquely identifies this request. |
Mandatory |
notifyURL |
(URI) the URL to which you would like to send the notification of redemption. |
Reserved |
callbackData |
(string) will be passed back in this notification. This is used to identify the tokens generated related to requests (or any other useful data, such as a function name). This is only valid if notifications are required. |
Optional |
smsText |
(string) Full SMS notification message. |
Optional |
Response
Following is a sample response of Apply Rewards.
{
"rewardsApplyResponse": {
"pin": null,
"amount": 25,
"type": "data",
"clientCorrelator": "123456",
"redemptionResponse": {
"notifyURL": "http://rewards-creating-application.com/notifyOfRedemptionURL",
"callbackData": "some-data-useful-to-the-requester"
},
"resourceURL": "http://10.62.160.154:8080/v0.1/rewards/777334035/apply"
}
}
The following are the Response parameters of Apply Rewards. All request parameters will be relayed in the response. Additionally resourceURL parameter will be added to the response.
Parameter name |
Description |
Usage |
amount |
(decimal) the value of the amount parameter will differ based on the {type}; sms – The number of SMS data – The amount of data in MB |
Mandatory |
type |
(string) the type of reward, if its sms or data |
Mandatory |
clientCorrelator |
(string) uniquely identifies this request. |
Mandatory |
callbackData |
(string) will be passed back in this notification. This is used to identify the tokens generated related to requests (or any other useful data, such as a function name). This is only valid if notifications are required |
Optional |
notifyURL |
(URI) the URL to which you would like to send the notification of redemption. |
Reserved |
resourceURL |
A reference URL to the request |
Mandatory |