NAV Navbar
Codes

Introduction

Thawani Wallet System (Portal) is the registry of the Third-Party merchant as a Thawani wallet Merchant. After Merchant registration you will get below details from Thawani System (It will be communicated via email). These details are required to call Access Token API.

  1. SourceID.
  2. Username.
  3. Password.
  4. Public key of Thawani Wallet.

Also, third party needs to share their Public key to Thawani Wallet System. This is required to decrypt the request.

  1. In access token request password is encrypted using Thawani Public key and decrypted at Thawani wallet end using Thawani system’s Private Key.
  2. In notification payment request message is encrypted using Third party Private key and decrypted at Thawani wallet end using Third Party’s Public Key.

Connectivity

Interface specification

Data Encryption

Encryption method is JSON Web Token (JWT) with RSA encryption. As per encryption technique it is required to share the Public key within both the parties as data is encrypted using private key or public key depend on the API call.

Message data must be encrypted using the given keys. (Keys will be provided during the integration).

Authorization

Access Token Request: In order to call Notification transaction API, third party needs an access token. To obtain the access token, Login API must be called. This is an authorization request for Third Party merchant.

Token (LOGIN) API will generate access token. The token will expire within a specific period of time, so you need to re-invoke the API request. To invoke token API, you need username, password, SourceID and Public Key of Thawani Wallet.

HTTP Method Endpoint
POST http://uat.thawani.om:7501/api/login

Header parameter

Content-type application/x-www-form-urlencoded

Request Body

Request Body contains following fields.

Sample Request:

POST /token HTTP/1.1
Host: http://uat.thawani.om:7501/api/login
Content-Type: application/x-www-form-urlencoded

body:
Trantype=LOGIN&sourceid=ThawaniSourceID&Msg=USERNAME=Thawani|PASSWORD=EasyPassword

Make sure to encrypt EasyPassword with ThawaniPublic key.

Request Fields:

name Mandatory dataType Description
TranType M String Transaction type of the request.
SourceID M String Source ID provided to the Third Party for identification.
Msg M String The message contains the customer data. This field is combination of fields mentioned in below table.

Message (Msg) Fields:

name Mandatory dataType Description
USERNAME M String Username provided by Thawani Wallet System after registering the merchant into the Thawani system.
PASSWORD M String Password provided by Thawani Wallet System after registering the merchant into the system. Password should be encrypted with public key using JWT method.(Public Key Shared by Thawani Wallet System).

Success Message:

{
  "Status":"00", 
  "Msg":[
          {"StatusCode":"00", 
          "Description":"Success", 
          "FirstName":"Third PartyTest",
          "LastName":"Test",
          "UserId":"40207",
          "LastLoginDate":"11:19, Jan 11,2018", 
          "Token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1bmlxdWVfbmFtZSI6Ijk3Njg5NTI4NTkiLCJuYmYiOjE1MTU2NTAwMTYsImV4cCI6MTUxNTY1MTIxNiwiaWF0IjoxNTE1NjUwMDE2fQ.V_sAL7c15NmTF7Cq7hddRsuaaqPU80G2qajMCYu5m0"}
         ],
  "TimeStamp":null
}

Response Message

Response message is in JSON format. Response Message is categorized between header fields and message fields in case of successful transaction. For failed messages it will only contain Header fields.

Header Fields:

fieldName Mandatory dataType Description
Status M String Status of processing the request message.
MSG M String Message with respect to the status code.
TimeStamp M String TimeStamp return by Thawani System.

Message (Msg) Fields:

fieldName dataType Description
StatusCode String Status of processing the request message.
Description String Indicates the status.
FirstName String First name of Thawani Wallet Merchantm.
LastName String Last name of Thawani Wallet Merchant.
UserId String Thawani Merchant ID required in Notification transaction API.
LastLoginDate String Last login date and time in the Thawani wallet.
Token String This token is required to pass in notification transaction API header part of authorization tag.

Notification Transaction Request

This API is used to initiate the Notification Payment request to the Thawani customer. To call this API you should have access token received from “LOGIN” request. Also, you need to encrypt the request message with your private Key using JWT encryption method. Pass the access Token value to Authorization Bearer.

HTTP Method Endpoint
POST http://uat.thawani.om:7501/api/ThirdParty

Header parameters

Content-type application/json
Authorization Bearer <Access Token>

Request Body:

REQUEST Parameters without Encryption:

{
  "TranType":"THTPTRANSACTION",
  "THAWANIMERCHID":"20004",
  "TPID":"33",
  "AMOUNT":"1",
  "THAWANICUSTNO":"9999888800",
  "REQTXNID":"44445",
  "TXNDATE":"2018-08-06",
  "REMARK":""
}

REQUEST Parameters with Encryption

"eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJ1bmlxdWVfbmFtZSI6IntcIlRyYW5UeX
BlXCI6XCJUSFRQVFJBTlNBQ1RJT05cIixcIlRIQVdBTklNRVJDSElEXCI6XCIyMDAwN
FwiLFwiVFBJRFwiOlwiMzNcIixcIkFNT1VOVFwiOlwiMVwiLFwiVEhBV0FOSUNVU1RO
T1wiOlwiOTk5OTg4ODgwMFwiLFwiUkVRVFhOSURcIjpcIjQ0NDQ1XCIsXCJUWE5EQ
VRFXCI6XCIyMDE4LTA4LTA2XCIsXCJSRU1BUktcIjpcIlwifSIsImlzcyI6IlRIQVdBTkkiLC
JhdWQiOiJJTlRFR1JBVElPTiIsImV4cCI6MTUzMzU1NTAzM30.eEP9C6Fnu7g3vicuZ60
qjqhXnOfw2HPTDfhoCSLTF5tU0tyApG8DrCzx6P1aUVdp_XWO72_0dFaU7J_Hom5qY
Sux_2mDsTHO-
4qyQfW_B00t0RypmaLGvmTK55HAnsWM1daSF9f4x_N3fAErYlLca3YRZLWSnyKOBV
B0QmWqdJtvQmwi7G3a6o6G7OFgB47aDv-
4VQxi1cq2FBH_dnxfqha9XoRLNhvBByaxIZZgxuyXs80ikPetZCiTIRVx3ZHxuVISJt-
G6OJfDzfNG9BvwopXLc0Q6v3em82tuH9-wX6c2WvngDCSfyUk3BV-
JtjwTI_xrx7TTH0uTsoSqq189A"

Sample Request:

POST /token HTTP/1.1
Host: http://uat.thawani.om:7501/api/ThirdParty
Content-Type: application/json

body:
{
  "REQUEST":"eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJ1bmlxdWVfbmFtZSI6IntcIl
            RyYW5UeXBlXCI6XCJUSFRQVFJBTlNBQ1RJT05cIixcIlRIQVdBTklNRVJDSElEXCI6X
            CIyMDAwNFwiLFwiVFBJRFwiOlwiMjMzNDNcIixcIkFNT1VOVFwiOlwiMVwiLFwiVEhBV0
            FOSUNVU1ROT1wiOlwiOTk5OTg4ODgwMFwiLFwiUkVRVFhOSURcIjpcIjQzNDM0Nlwi
            LFwiVFhOREFURVwiOlwiMjAxNy0xMi0zMVwiLFwiUkVNQVJLXCI6XCJcIn0iLCJpc3Mi
            OiJUSEFXQU5JIiwiYXVkIjoiSU5URUdSQVRJT04iLCJleHAiOjE1MzMzNzk3OTJ9.Jpntx
            GfwRbx6xP2A3v_sFfHJ56DOQc6T9rt2yuhNe1041GrhwmwylwYBixF2aaTKOOYf8ufyQ
            Bv9eNcY5wH5UONJe43iDgvSWoqJdl1WRgepqapGm_fJIZq7fgD1nwDO6bESfhKtBFwy
            yzEuLHtqcZmUUZ02vrZ8nQRhbFDbqmxYVs5kmcruBOX15vFLCsVrR8G5YKcJR_i_TZ
            7itj2iZLsUh2nzK_5zSU2VxCdfEm7zZaznzWmaCmUuK9bWxVW3bKIF_-
            nyno4X7TOF0nqbGXmHLY4TB7Im-
            l2z0K8HNF6_DZlCpBnhXEWpNaox5Lxz09TmMwmmX62SavdOhRkSuw",
  "SOURCEID":"XXXXXXXXXXXXXXXXX"
}

The Request body contains the following details. REQUEST attribute in the request body should be encrypted with Third party Private Key using JWT method using algorithm RS256. See the sample example.

Request (REQUEST) Body Fields:

name Mandatory dataType Description
SourceID M String Source ID provided to the client for identification.
REQUEST M String Message contains json string of below field encrypted using private key.

Request (REQUEST) Fields:

fieldName Mandatory dataType Description
TranType M String (THTPTRANSACTION) Fixed value passed for Enquiry API
THAWANIMERCHID M String Thawani wallet merchant ID Shared by Thawani system.
TPID M AlphaNumeric Third Party mobile number who is initiating the notification transaction payment/IdentificationNo.
AMOUNT M Numeric Transaction Amount for payment.
THAWANICUSTNO O String Thawani wallet customer’s mobile number to whom notification to be received.
REQTXNID M String Third party Unique transaction reference ID.
TXNDATE M DateTime Transaction date having “YYYY-MM-DD” format.
REMARK O String Remark if any.

Sample Response Success Message:

{
  "Status": "00",
  "Msg": [
            {"ReferenceNo":"E27397480"}
         ],
  "TimeStamp": "1533551849"
}

Failed Message:

{
  "Status":"916","Msg":"Sender detail not found."
}

Response Message

Response message is in JSON format. Response Message is categorized between header fields and message fields in case of successful transaction. For failed messages it will only contain Header fields.

Header Fields:

fieldName Mandatory dataType Description
Status M String Status of processing the request message.
Msg M String Message with respect to the status code. If success it will return reference number in JSON else give error message in string format.

Message (Msg) Fields:

fieldName dataType Description
ReferenceNo String In case of successful transaction Thawani wallet unique reference number

Third Party Transaction Enquiry API

Third Party will call this API after transaction notification request is accepted by customer to know transaction’s current status.

HTTP Method Endpoint
POST http://uat.thawani.om:7501/api/ThirdParty

Header parameters

Content-type application/json
Authorization Bearer <Access Token>

Sample Request:

POST /token HTTP/1.1
Host: http://uat.thawani.om:7501/api/ThirdParty
Content-Type: application/json

Without Encryption:

{
  "TranType":"THTPSTATUSENQUIRY",
  "THAWANIMERCHID":"20004",
  "THAWANICUS TNO":"9763265696",
  "REQTXNID":"77777772",
  "TXNDATE":"2018-08-06"
}

With Encryption:

"eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJ1bmlxdWVfbmFtZSI6IntcIlRyYW5UeX
BlXCI6XCJUSFRQVFJBTlNBQ1RJT05cIixcIlRIQVdBTklNRVJDSElEXCI6XCIyMDAwN
FwiLFwiVFBJRFwiOlwiMzNcIixcIkFNT1VOVFwiOlwiMVwiLFwiVEhBV0FOSUNVU1RO
T1wiOlwiOTk5OTg4ODgwMFwiLFwiUkVRVFhOSURcIjpcIjQ0NDQ1XCIsXCJUWE5EQ
VRFXCI6XCIyMDE4LTA4LTA2XCIsXCJSRU1BUktcIjpcIlwifSIsImlzcyI6IlRIQVdBTkkiL
CJhdWQiOiJJTlRFR1JBVElPTiIsImV4cCI6MTUzMzU1NTAzM30.eEP9C6Fnu7g3vicuZ
60
qjqhXnOfw2HPTDfhoCSLTF5tU0tyApG8DrCzx6P1aUVdp_XWO72_0dFaU7J_Hom5qY
Sux_2mDsTHO-
4qyQfW_B00t0RypmaLGvmTK55HAnsWM1daSF9f4x_N3fAErYlLca3YRZLWSnyKOBV
B0QmWqdJtvQmwi7G3a6o6G7OFgB47aDv-
THAWANI WAYYAK API4VQxi1cq2FBH_dnxfqha9XoRLNhvBByaxIZZgxuyXs80ikPetZCiTIRVx3ZHxuVISJt-
G6OJfDzfNG9BvwopXLc0Q6v3em82tuH9-wX6c2WvngDCSfyUk3BV-
JtjwTI_xrx7TTH0uTsoSqq189A"

Sample Request with Encrypted value:

{
  "REQUEST":"eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJ1bmlxdWVfbmFtZSI6IntcI
            lRyYW5UeXBlXCI6XCJUSFBUUkFOSElTVE9SWVwiLFwiVEhBV0FOSU1FUkNISURcI
            jpcIjIwMDA0XCIsXCJUSEFXQU5JQ1VTVE5PXCI6XCJcIixcIlJFUVRYTklEXCI6XCJcIix
            cIlRYTkRBVEVcIjpcIlwiLFwiU1RBUlREQVRFXCI6XCJcIixcIkVORERBVEVcIjpcIlwiLFwi
            TEFTVFRSQU5DT1VOVFwiOlwiMFwiLFwiU1RBVFVTXCI6XCJcIixcIlJFQ09SRENPVU
            5UXCI6XCJcIn0iLCJpc3MiOiJUSEFXQU5JIiwiYXVkIjoiSU5URUdSQVRJT04iLCJleHAi
            OjE1NDA0NzA1NDh9.IuHf8hVf6SDziigOtlvU-
            DlB1k0mVhKfU60Gu44ovKZxeGaKFqSc6vS4cjfvZa7K64-erKCBkPZ-
            W9SppqOLE8juGoUzXo3LZoMPyzMLJncEaWCtKgQB47uDDHIh7m3mptJ2FGj9ZpJqp
            zNkzlMaZcNylVMYT4v77ASTpf2860gcb9bIEj7Pzvp_MfTjxI37iX5hXFBnyvGTmLU-
            xxUjIxMkLisuOO-gm3DgKHb62lGJJI3AxCbMhRlHBUIjav0A6b2b3-
            3qNPeBaNgRVTyqJWgypTQI3uNDnqI6sOr9yRoKRV9JgIHS5GYkJgy_mvKlZueJyFmA_kB4xi6Z-i5rdw",
  "SOURCEID":"XXXXXXXXXXXXXXXXX"
}

Request Message

Request Message is categorized between header fields and message fields. Request message should be encrypted with Third party Private Key using JWT method.

Header Fields:

fieldName Mandatory dataType
SourceID M String
REQUEST M String

Message (REQUEST) Fields:

fieldName Mandatory dataType Description
TranType M String (THTPSTATUSENQUIRY) Fixed value passed for Enquiry API.
THAWANIMERCHID M String Thawani wallet merchant ID Shared by Thawani system.
THAWANICUSTNO O String Thawani wallet customer’s mobile number to whom notification to be received.
REQTXNID M String Third party Unique transaction reference ID.
TXNDATE M DateTime Transaction date having “YYYY-MM-DD” format.

Sample Response Success:

{
  "Status":"00",
  "Msg":[
          {
            "STATUSCODE":"00",
            "Description":"Success",
            "MerchantID":"30229",
            "MerhcantName":"zuber",
            "TranAmount":1.0000000,
            "Customer Mobile ":"71119298",
            "TranDate":"Date(1540800322213)",
            "ThirdPartyTranID":"2323",
            "ThawaniTranID":"830280000002"
          }
        ],
  "TimeStamp":"1540800346"
}

Response Failed

{
  "Status": "922",
  "Msg": "Transaction is pending.",
  "TimeStamp": "1540562800"
}

Response Message

Response message is in JSON format. Response Message is categorized between header fields and message fields in case of successful transaction. For failed messages it will only contain Header fields.

Header Fields:

fieldName Mandatory dataType
Status M String
Msg M String
TimeStamp M String

Message (Msg) Fields:

fieldName dataType Description
Msg String If transaction exists in thawani system with passed parameters then response will be in JArray format else it will be in plain text.

Third Party Transaction History API

This API is for generating report of Third party transactions.

HTTP Method Endpoint
POST http://uat.thawani.om:7501/api/ThirdParty

Header parameters

Content-type application/json
Authorization Bearer <Access Token>

Sample Request:

POST /token HTTP/1.1
Host: http://uat.thawani.om:7501/api/ThirdParty
Content-Type: application/json

Without Encryption:


{
  "TranType":"THPTRANHISTORY",
  "THAWANIMERCHID":"20004",
  "THAWANICUSTNO ":"",
  "REQTXNID":"",
  "TXNDATE":"",
  "STARTDATE":"2018-08-05 19:14:50.880",
  "ENDDATE":"2018-08-06 19:14:50.880", 
  "LASTTRANCOUNT":"0",
  "STATUS":"",
  "RECORDCOUNT":"10"
}

With Encryption:


"eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJ1bmlxdWVfbmFtZSI6IntcIlRyYW5UeX
BlXCI6XCJUSFRQVFJBTlNBQ1RJT05cIixcIlRIQVdBTklNRVJDSElEXCI6XCIyMDAwN
FwiLFwiVFBJRFwiOlwiMzNcIixcIkFNT1VOVFwiOlwiMVwiLFwiVEhBV0FOSUNVU1RO
T1wiOlwiOTk5OTg4ODgwMFwiLFwiUkVRVFhOSURcIjpcIjQ0NDQ1XCIsXCJUWE5EQ
VRFXCI6XCIyMDE4LTA4LTA2XCIsXCJSRU1BUktcIjpcIlwifSIsImlzcyI6IlRIQVdBTkkiLC
JhdWQiOiJJTlRFR1JBVElPTiIsImV4cCI6MTUzMzU1NTAzM30.eEP9C6Fnu7g3vicuZ60
qjqhXnOfw2HPTDfhoCSLTF5tU0tyApG8DrCzx6P1aUVdp_XWO72_0dFaU7J_Hom5qY
Sux_2mDsTHO-
4qyQfW_B00t0RypmaLGvmTK55HAnsWM1daSF9f4x_N3fAErYlLca3YRZLWSnyKOBV
B0QmWqdJtvQmwi7G3a6o6G7OFgB47aDv-
4VQxi1cq2FBH_dnxfqha9XoRLNhvBByaxIZZgxuyXs80ikPetZCiTIRVx3ZHxuVISJt-
G6OJfDzfNG9BvwopXLc0Q6v3em82tuH9-wX6c2WvngDCSfyUk3BV-
JtjwTI_xrx7TTH0uTsoSqq189A"

Sample Request with Encrypted value:

{
  "REQUEST":"eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJ1bmlxdWVfbmFtZSI
             6IntcI
             lRyYW5UeXBlXCI6XCJUSFBUUkFOSElTVE9SWVwiLFwiVEhBV0FOSU1FUkNIS
             URcI
             jpcIjIwMDA0XCIsXCJUSEFXQU5JQ1VTVE5PXCI6XCJcIixcIlJFUVRYTklEXCI6XC
             JcIix
             cIlRYTkRBVEVcIjpcIlwiLFwiU1RBUlREQVRFXCI6XCJcIixcIkVORERBVEVcIjpcIlwi
             LFwi
             TEFTVFRSQU5DT1VOVFwiOlwiMFwiLFwiU1RBVFVTXCI6XCJcIixcIlJFQ09SREN
             PVU
             5UXCI6XCJcIn0iLCJpc3MiOiJUSEFXQU5JIiwiYXVkIjoiSU5URUdSQVRJT04iLCJl
             eHAi OjE1NDA0NzA1NDh9.IuHf8hVf6SDziigOtlvU-
             DlB1k0mVhKfU60Gu44ovKZxeGaKFqSc6vS4cjfvZa7K64-erKCBkPZ-
             W9SppqOLE8juGoUzXo3LZoMPyzMLJncEaWCtKgQB47uDDHIh7m3mptJ2FGj9Z
             pJqp
             zNkzlMaZcNylVMYT4v77ASTpf2860gcb9bIEj7Pzvp_MfTjxI37iX5hXFBnyvGTmLU
             - xxUjIxMkLisuOO-gm3DgKHb62lGJJI3AxCbMhRlHBUIjav0A6b2b3-
             3qNPeBaNgRVTyqJWgypTQI3uNDnqI6sOr9yRoKRV9JgIHS5GYkJgy_mvKlZueJy
             FmA
             _kB4xi6Z-i5rdw",
  "SOURCEID":"XXXXXXXXXXXXXXXXX"
}

Request Message

Request Message is categorized between header fields and message fields. Request message should be encrypted with Third party Private Key using JWT method.

Header Fields:

fieldName Mandatory dataType
SourceID M String
REQUEST M String

Message (Msg) Fields:

fieldName Mandatory dataType Description
TranType M String (THPTRANHISTORY) Fixed value passed for Transaction HistoryAPI.
THAWANIMERCHID M String Merchant's Unique ID Provided by Thawani.
THAWANICUSTNO O String Thawani system's Customer's Mobile No, who had performed transaction.
REQTXNID O String Third Party Request Unique ID sent at time of Transaction request.
TXNDATE O Date (yyyy-mm-dd) Single date of which Report to be generated.
STARTDATE O DateTime (yyyy-mm-dd hh:mm:ss.sss) From when transaction report to be generated.
ENDDATE O DateTime (yyyy-mm-dd hh:mm:ss.sss) Till when transaction report to be generated.
LASTTRANCOUNT M Integer 0 for first x records. for fetching next x records value will be ID column value of last record of current response.
STATUS O String 1 – For Pending Notification Request, 2 - For Accepted Notification, Request, 3 – Rejected Notification Requests.
RECORDCOUNT M Integer Number of Records required to be included in Report. Max limit 20 per request.

Sample Response Success:

{
  "Status": "00",
  "Msg": [
          {
            "ID":1,
            "STATUSCODE":"1007",
            "TransactionStatus":"Suspect",
            "MerchantID":"20004",
            "MerchantName":"sagaerrgs",
            "TranAmount":"1.000",
            "CustomerName":"Abc",
            "CustomerMobile":"xxxxxxxx",
            "TranDate":"Aug 6 2018 7:16PM",
            "ThirdPartyTranID":"77777772",
            "ThawaniTranID":"",
            "NotificationStatus":"Transaction is pending.",
            "NotificationDate":"Aug 6 2018 7:14PM"
          }
        ],
  "TimeStamp": "1540467343"
}

Response Failed:

{
  "Status":"1006",
  "Msg":"No Transaction found.", 
  "TimeStamp":"1540467221"
}

Response Message

Response message is in JSON format. Response Message is categorized between header fields and message fields in case of successful transaction. For failed messages it will only contain Header fields.

Header Fields:

fieldName Mandatory dataType
Status M String
Msg M String
TimeStamp M String

Message (Msg) Fields:

fieldName dataType Description
Msg String If transactions exists in thawani system with passed parameters then response will be in JArray format else it will be in plain text.