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.

Fig: System Interaction with partner/client server for token based payment in 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:

Inquiry

eSewa calls the partner/clilent's server with the token entered from user as in process 1.1 shown in figure above. If the required token is valid, response (1.2) is sent to eSewa with the necessary parameters required for payment. If the token is invalid or duplicate, error message is sent from partner/client, which is accordingly displayed to the customer. Below is the API detail-
Request-
Request is made with the unique request id or token generated by client. Request Method type – GET **Basic authentication(using username and password) should be provided in header for every request.
URL:
URL provided by the client to eSewa.
Update:
{request_id}
should be sent as path variable

Description

Field Name Parameter Type Field Description
request_id String unique request id or token provided to the user which is generated by partner/client
Response

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

Field name Parameter Type Field Description
request_id String unique request id or token provided to the user which is generated by partner/client
response_message String Response error message
response_code int This is the response provided by client to eSewa to know the successful completion of any transaction.-0 Success -1 Failed
amount double Total amount to be paid by the customer.
properties Map Fields in properties are dynamic as per clients. Any values may be passed in properties. Key and value both should be String.

Example:Statement Request-

Request URI- client's url/{request_id} Method type - GET Path variable - request_id GET: {{base_url}}/inquiry/12123122

Case:Success
{
 "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"           
 }
} 
Success Response II(In case of Package Selection)
{
    "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
            }
        }
    ]
} 
Case:Failure
{
  "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

Payment

Request Method type - POST

**Basic authentication(using username and password) should be provided in header for every request.

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

where,

Field Name Parameter Type Field Description
request_id String unique request id or token provided to the user which is generated by partner/client
amount double Total amount to be paid by the customer.
transaction_code String Code generated from eSewa during payment.
Response

Below is the response received for the above request made -

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

where,

Field Name Parameter Type Field Description
request_id String unique request id or token provided to the user which is generated by partner/client
response_message String Response error message / Response message
response_code int This is the response provided by client to eSewa to know the successful completion of any transaction. -0 Success -1 Failed
amount double Total amount to be paid by the customer.
reference_code String Client side code, which might be helpful during reconciliation.
Example:Payment Request-

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),
} 
Case:Success
{
  "request_id": "12123122",
  "response_code": 0,
  "status":"SUCCESS", 
  "response_message": "Payment successful",
  "amount": "1000",
  "reference_code": "12client34"
} 
Case:Failure
{
  "response_code": 1,
  "response_message": "Invalid token"
} 

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

Status Check

Request Method type - POST

**Basic authentication(using username and password) should be provided in header for every request.

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

where,

Field Name Parameter Type Field Description
request_id String unique request id or token provided to the user which is generated by partner/client
amount double Total amount to be paid by the customer.
transaction_code String Code generated from eSewa during payment.
Response

Below is the response received for the above request made -

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

where,

Field Name Parameter Type Field Description
request_id String unique request id or token provided to the user which is generated by partner/client
response_message String Response error message / Response message
response_code int This is the response provided by client to eSewa to know the successful completion of any transaction. -0 Success -1 Failed
amount double Total amount to be paid by the customer.
reference_code String Client side code, which might be helpful during reconciliation.
Example:Status Check-

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

{
  "request_id": "12123122",
  "amount": 1000,
  "transaction_code": "01XV31A"
} 
Case:Success
{
  "request_id": "1234",
  "response_code": 0,
  "status": "SUCCESS/FAILED"
  "response_message": "Payment successful",
  "amount": 1000,
  "reference_code": "ABCD"
}  
Case:Failure
{
  "response_code": 1,
  "response_message": "Payment not found"
}