API SPECIFICATION FOR API USER
VERSION 2.1.2
Release Date Modification Author
1.0 2021-10-21 Beta CloudWell Limited
[CURRENTLY AVAILABLE ONLY IN ENGLISH]
Prepared by-
CloudWell Limited
Skill House, House-Ka-53/2 (7th Floor),
Progoti Sarani, Shahjadpur, Gulshan, Dhaka 1212
Phone: +88029860070, FAX: +88028831236
Email:
[email protected]\
BASE-URL
https://agentapi.paywellonline.com
TOKEN GENERATION
Firstly, you have to make a request to the following URL to get a security token. Store this
security token for generating TOKEN each time for making request to different APIs. This
token will expire after 8 hours. If you get “timeout token” as response, then you have to call
this method again for generating fresh security token and store that for further process.
API URL: BASE-URL/Authentication/PaywellAuth/getToken
Method: POST
Request Header:
Key Value Description
Authorization BasicAUTH-VALUE AUTH-VALUE = BASE64 encoded value of
APIUserName: APIPassword Here,
APIUserName = It will be provided by PayWell
APIPassword = It will be provided by PayWell
Request Body: None
Example Code:
APIUserName = "Abc"
APIPassword = "123"
AUTH-VALUE = base64_encode(APIUserName:APIPassword)
Sample Response:
Success response Failed Response
{"status":200,"message":"success","token":{"security_token":"eyJ {"status": 313,"message":
0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJpYXQiOjE1Njk5O "Authentication Error" }
TYyNzAsImp0aSI6IkFLRlVCZDVObDBWZzZ6Z1pnS0NkM3J1
N1dBVTRhb1BFOGtOUmNaUEIyRlE9IiwiaXNzIjoiaHR0cHM
6XC9cL2FnZW50YXBpLnBheXdlbGxvbmxpbmUuY29 tXC9Q
YXl3ZWxsQXV0aFwvZ2V0VG9rZW4iLCJuYmYiOjE1Njk5OT
YyODAsImV4cCI6MTU3MDAyNTA4MCwiZGF0YSI6eyJ1c2V
yX3R5cGUiOiJBUEkiLCJ1c2VyX25hbWUiOiJhaXJfdGlja2V0X
3Rlc3QiLCJ1c2VyX2lkIjoiMTc4MCJ9fQ.XiyPq6wQ9eyK_vE0s
y3LZ0xDjPZUgl3zzcHEt6alPgYEoPY6ZxggTBoRIiojqoegPqab7
nn6Prmp2JKuD6bhQ","token_exp_time":"28800s","token_type":
"Bearer","ack_timestamp":"2019-10- 02T12:04:30+06:00"}}
Note: Store this “security_token” for creating bearer TOKEN.
Bearer TOKEN generation for making request to different APIs:
Basically TOKEN contains three parts (concatenated with colon) as follow: SECURITY-
TOKEN: API-KEY: HASHED-DATA
Here,
1. SECURITY-TOKEN is received from Token Generation API.
2. API-KEY will be provided by PayWell.
3. HASHED-DATA is a generated keyed hashed value of the request data in JSON format.
HASHED-DATA generation process:
1. Request data sample: {“field1”: “field1_value”, “field2”: “field2_value”}
2. Generate keyed hash value of the request data using HMAC, ENCRYPTION-KEY and
“sha256” algorithm.
Note: ENCRYPTION-KEY will be provided by PayWell.
Example Code:
Mobile Recharge
API URL: BASE-URL/Recharge/mobileRecharge/singleTopup
Call Method: POST
Content Type: application/json
Request Header:
Key Value
Authorization Bearer TOKEN
Input parameters:
Key Description
username required Client Username
password required Client Password.
ref_id required Alphanumeric 15 digit unique transaction id
msisdn required Recharge Mobile Number
amount required Recharge Amount
con_type optional prepaid or pospaid
operator required Mobile Operator Short Name (Short name will be found from Operator
portion)
OutletCode optional Unique user outlet code(only for selected user)
Request Body: JSON
Sample Data:
Request Body Success Response
{"username": "**********", "password": {"hotlineNumber":"09666773333","data":
"*******", "re f_id": {"status":200,"message":"Successful","trans_id":"PDS00
"XXXXXXXXXXXXXXX", "msisdn": 00000040690348","topupData":
"01XXXXXXXXX", "amount": XX, {"msisdn":"01670869075","amount":10,"con_type":"pre
"con_type": "prepaid/ pospaid", paid","operator":"AT","clientTrxId":"testtransaction"}}}
"operator": "AT"}
Success Response
{"hotlineNumber": "09666773333", "data":
{"status":"602", "message": "Hash not matched.",
"trans_id": "PDS202006072204422911", "top
upData":{"msisdn": "01670869075", "amount": 10,
"con_type": "pre paid", "operator": "A", "clientTrxId":
"testtransaction"}}}
Operator:
Operator Name Short Name
GrameenPhene GP
Banglalink BL
Robi RB
Airtel RB
Airtel TT
Skitto GP ST
Mobile Recharge Enquiry
API URL: BASE-URL/Recharge/mobileRecharge/mobileRechargeEnquiry
Call Method: POST
Content Type: application/json
Request Header:
Key Value
Authorization Bearer TOKEN
Input parameters:
Key Type Description
username Required Client Username
msisdn Required Mobile Number For Enquiry
Request Body: JSON
Sample Data:
Request Body Success Response
{"username":"******","msisdn":"01XXXXXX {"status_code":200,"message":"Successful","enquiryData":
{"status_code":"200","tran_id":"testtransaction","status_name":"Su
XXX"} ccessful","recipient_msisdn":"01670869075","operator_name":"Air
tel","amount":"10.00","connection_type":"prepaid","request_date":"
2020-06-07 20:53:08"},"hotline":"0966677333"}
Error Response
{"status_code":"602","message":"Hash not
matched.","hotline":"0966677333"}
Mobile Recharge Enquiry Through Transaction Id
API URL: BASE-URL/Recharge/mobileRecharge/mobileRechargeEnquiryThroughtrxId
Call Method: POST
Content Type: application/json
Request Header:
Key Value
Authorization Bearer TOKEN
Input parameters:
Key Type Description
username Required Client Username
trxId Required PayWell transaction Id or user provided transaction id
Request Body: JSON
Sample Data:
Request Body Success Response
{"username":"******","trxId":"XXXX {"status_code": 200, "message": "Successful",
XXXX "enquiryData":
XXX"} {"status_code":"200","tran_id":"testtransaction","status_
name": "Successful", "recipient_msisdn":
"01670869075", "operator_name": "Airtel",
"amount":"10", "connection_type": "prepaid",
"request_date":"2020-06-07 20:53:08"}, "hotline":
"0966677333" }
Error Response
{"status_code":"602","message":"Hash not
matched.","hotline":"0966677333"}
Mobile Recharge Offer
API URL: BASE-URL/Recharge/mobileRecharge/topUpOffer
Call Method: POST
Content Type: application/json
Request Header:
Key Value
Authorization Bearer TOKEN
Input parameters:
Key Type Description
username Required Client Username
operator Required Mobile Operator Short Name (Short name will be found from
Operator portion)
Request Body: JSON
Sample Data:
Request Body Success Response
{"username":"***","operator {"status_code":200,"message":"Successful","RechargeOffer":[{
":"XX"} "sub_service_name": "GrameenPhone","amount": "37","remarks":
"30 Min (Any Net) + 512 MB For 72 Hrs","type": "1"},
{"sub_service_name": "GrameenPhone","amount": "14","remarks":
"21 Min (Any Operator) For 16 Hrs\r\n","type": "2"},
{"sub_service_name": "GrameenPhone","amount": "13","remarks":
"35 MB For 3 Days","type": "3"}]}
Error Response
{"status_code":"602","message":"Hash not
matched.","hotline":"0966677333"}
If the value of type is 1 then this is a “combo offer”, if the value is 2 then this offer is for “Talk
Time” if the value is 3 then this offer is for “Internet”
Retailer Balance checking
API URL: BASE-URL/Retailer/RetailerService/retailerBalance
Call Method: POST
Content Type: application/json
Request Header:
Key Value
Authorization Bearer TOKEN
Input parameters:
Key Type Description
username Required Client Username
password Required Client password
Request Body: JSON
Sample Data:
Request Body Success Response
{"username":"*****"," {"status":200,"message":"Successful","retailerCode":"W12120050771","b
password":"XXXX "} alanceData":{"balance":"0.00000"}}
Error Response
{"status":"602","message":"Hash not matched.","retailerCode":"",
"balance Data":{"balance":""}}
Status Code And Meaning
Status Status Message Description
200 Successful Transaction completed
309 Technical Error There is a technical error for this operator
which is unavailable at the moment
300 Error Processing Error Processing
301 Service Not Rendered Service Not Rendered
302 Invalid Number Invalid Number
304 Invalid TopUP Value Invalid TopUP Value
307 Time Limit Error Time Limit Error
309 Technical Error Technical Error
310 Service Unavailable The Recharge service unavailable at this
moment. Pls try again later
311 Can Not Be Processed Can Not Be Processed
312 Technical Issue Technical Issue
313 Authentication Error Authentication Error
346 Invalid Connection Type Invalid Connection Type
347 Technical Fault Technical Fault
348 Invalid Operator Invalid Operator
354 Time limit error, you can't recharge same Time limit error, you can't recharge same
number and same amount within 5 number and same amount within 5 minutes
minutes
360 Insufficient Input, you are missing Insufficient Input, you are missing some
some mandatory field mandatory field
365 Not enough balance Not enough balance
368 Topup Failed Topup Failed
600 Request body not found!!! Request body not found!!!
601 Request body invalid!!!! Request body invalid!!!!
602 Hash not matched. Hash not matched.
603 Token time has been expired. Token time has been expired.
604 Token signature is not valid. Token signature is not valid.
605 Unauthorized key/Token!!!. Unauthorized key/Token!!!.
606 Token parts are missing. Token parts are missing.
607 Invalid IP. Invalid IP.
610 Hash not matched. Hash not matched.
801 Invalid Amount Invalid Amount
