Overview

API, an abbreviation of Application Program Interface, is a set of routines, protocols, and tools for building software applications. The API specifies how software components should interact. Virtually all software has to request other software to do some things for it. To accomplish this, the asking program uses a set of standardized requests, called Application Programming Interface (API). Building an application with no APIs is basically like building a house with no doors. The API for all computing purposes is how we open the blinds and the doors and exchange information. This documentation is about Token based payment in eSewa. This helps to understand and guide those partners which are intended to integrate token based payment. Token based payment implies, a unique token is generated at the merchant end. Customer enters the token at eSewa for payment, and then request is made to the client against the token generated from merchant. Upon getting the necessary information in response, payment is made from eSewa in next step. This documentation will help to accelerate the integration efforts of client application with eSewa.

The scenario visualized in above figure shows an overall communication from partner/client's Server to eSewa and finally to the partner/client's Server. Number in bracket specifies the order of process that is carried out between partner client and eSewa. Following lays the explanation:

Authentication

eSewa supports two types of Authentication methods • Basic Authentication: In Basic Authentication, username and password should be provided in header for every request • Bearer Access Token:In Bearer Token Authentication, the server issues a token after successful authentication. The client includes this token in the HTTP Authorization header for subsequent requests. The server then validates the token to grant access. URL:{{base_url}}/access-token Url for login as well as for refreshing token will be same Method:POST

{
"grant_type": "password/refresh_token",
"client_secret": {{base64 encoded client_secret key}},
"username": {{username}},
"password": {{base64 encoded password}}
} 

{
 "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJqa1ZhNWI2TzZpNTJIeEdHSUN3NFhVTkFyLWpxSUs3",
 "expires_in": 250,
 "token_type": "Bearer",
 "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJkYTNlYjFjZS0wNGJlLTQ3Y2YtODlkYS02M2M5MDJ",
 "refresh_expires_in": 550
} 

With above response from client. Esewa send's access Token for Authentication for each request. In Header with key- Authorization. Key is constructed as : token_type + “<space>“ + access_token Refresh Token: To refresh the token same authentication url is used with following request format :

{
"grant_type": "refresh_token",
"refresh_token": {{refresh_token from previous login}},
"client_secret": {{base64 encoded client_secret key}}
} 

{
"access_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJqa1ZhNWI2TzZpNTJIeEdHSUN3NFhVTkFyLWpxSUs3",
"expires_in": 200,
"token_type": "Bearer",
"refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJkYTNlYjFjZS0wNGJlLTQ3Y2YtODlkYS02M2M5MDJk",
"refresh_expires_in": 400
} 

Note: Field name either in header, url or in body must always be in snake case i.e if we've field “Customer Id” it must always be as “customer_id”

Description

Below is the response received for the above request made -

{
    "request_id": "",      
    "response_code" : "",
    "response_message": "",
    "amount": "",
    "properties": {
      "name": ""
      //address... and other parameters as per merchants (used as detail)
    }
 } 

where

Example:Statement Request-

Request URI- client's url/{request_id}       client's url/{request_id}/{mobile_number}(incase of multiple parameters) Method type - GET Path variable - request_id GET: {{base_url}}/inquiry/12123122(incase of single parameter)   {{base_url}}/inquiry/12123122/9806800001(incase of multiple parameters)

{
 "request_id": "12123122",      
 "response_code" : 0,
 "response_message": "success",
 "amount": 1000,
 "properties": {
     "customer_name": "Ram Kumar Thapa",
     "address" : "Kathmandu",
     "customer_id": "1A4DDF",
     "invoice_number": "123456789",
     "product_name": "ABC online registration"           
 }
} 

{
    "amount": 2499,
    "request_id": "abhishek@gmail.com",
    "response_code": 0,
    "response_message": "success",
    "properties": {
        "username": "abhishek@gmail.com",
        "expiry_date": "2027-07-03",
        "phone": "9806800001"
    },
    "packages": [
        {
            "display": "One Month Package. [ 1 Month at 499 ]",
            "value": 499,
            "properties": {
                "package_id": 1
            }
        },
        {
            "display": "Three Months Package. [ 3 Months at 999 ]",
            "value": 999,
            "properties": {
                "package_id": 2
            }
        },
        {
            "display": "1 Year Package. [ 1 Year at 2499 ]",
            "value": 2499,
            "properties": {
                "package_id": 3
            }
        },
        {
            "display": "Special Package: Buy 2 Years, Get 1 Year Free. [ 3 Years at 4999 ]",
            "value": 4999,
            "properties": {
                "package_id": 4
            }
        }
    ]
} 

{
  "response_code" : 1,
  "response_message" : "Invalid token"    
}
 

Note:- fields in properties are dynamic as per clients. Any values may be passed in properties key and value both should be String

{
 "request_id": "",
 "amount": "",
 "transaction_code": ""
} 

where,

Below is the response received for the above request made -

{
 "request_id" : "",
 "response_code": "",
 "response_message": "",
 "amount": "",
 "reference_code": ""
} 

where,

Request URI- client's payment URI Method type - POST POST : {{base_url}}/payment

{
  "request_id": "12123122",
  "amount": 1000,
  "transaction_code": "01XV31A",
  "package_id": 1(Incase of package selection)
} 

{
  "request_id": "12123122",
  "response_code": 0,
  "response_message": "Payment successful",
  "amount": "1000",
  "reference_code": "12client34"
} 

{
  "response_code": 1,
  "response_message": "Invalid token"
} 

Note:- reference_code is generated from clients while making payment .

{
 "request_id": "",
 "amount": "",
 "transaction_code": ""
} 

where,

Below is the response received for the above request made -

{
 "request_id" : "",
 "response_code": "",
 "status": "",
 "response_message": "",
 "amount": "",
 "reference_code": ""
} 

where,

Request URI- client's payment URI Method type - POST POST : {{base_url}}/status

{
  "request_id": "12123122",
  "amount": 1000,
  "transaction_code": "01XV31A"
} 

{
  "request_id": "1234",
  "response_code": 0,
  "status": "SUCCESS"
  "response_message": "Payment successful",
  "amount": 1000,
  "reference_code": "ABCD"
}  

{
  "request_id": "1234",
  "response_code": 1,
  "status": "FAILED"
  "response_message": "Payment Not Found",
  "amount": 1000,
  "reference_code": ""
}