Overview

The eSewa ePay system enables partner merchants to perform a transaction and receive money from the customer having an eSewa account in a secure environment.

Transaction Flow

1. When user choses eSewa as on-line payment option from partner merchant application, then user is temporarily redirected to eSewa ePay login page.
2. User will provide valid credentials on login page.
3. By confirming the transaction, user is accepting the transaction details sent by partner merchants.
4. After each successful transaction, the user is redirected back to partner merchant’s success page. If transaction fails due to any reason (which includes user canceling transaction), the user is informed by appropriate failure message and redirected back to partner merchant’s failure page.
5. For every successful transaction, the merchant account is credited accordingly and notified via email/SMS regarding transaction.
6. eSewa application will automatically notifies partner merchant related to eSewa transaction through Instant Payment Notification (IPN).
7. Partner merchants need to invoke transaction verification request to verify potential fraudulent transactions occurred.
8. eSewa application will automatically notifies partner merchant with either success or failure response.

System Interaction

The interactions required to complete a transaction followed by transaction verification process are shown below:

Fig: System interaction for payment with transaction verification process

The scenario visualized in above figure shows an overall communication diagram end to end from merchant to eSewa. In general, merchant sends payment request to eSewa for transaction, where user will login with valid credentials and confirms the transaction. Upon confirmation, user is redirected back to merchant’s success page. The merchant have to send transaction verification request to eSewa after receiving successful payment for filtering potential fraudulent transactions. The eSewa system will response back accordingly with either success or failure message.

HMAC/SHA256

This HMAC implements the HMAC algorithm as defined in RFC 2104 using the message digest function SHA256. The result MAC value will be a base-64 output type.

Input

Input should be string type and the value of Signed_field_names
Parameters(total_amount,transaction_uuid,product_code) should be mandatory and should be in the same order while creating the signature

total_amount=100,transaction_uuid=11-201-13,product_code=EPAYTEST

SecretKey:

SecretKey for every merchant partner will be provided from eSewa
For UAT, SecretKey will be 8gBm/:&EnhH.1/q( Input should be text type.)

Algorithm used for signature generation is SHA-256

Output:

The generated signature should be in base-64 output type. For eg:

Result

4Ov7pCI1zIOdwtV2BRMUNjz1upIlT/COTxfLhWvVurE=

Examples of creating base64 hashes using HMAC SHA256 in different languages:

<script src="https://cdnjs.cloudflare.com/ajax/libs/crypto-js/3.1.9-1
/crypto-js.min.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/crypto-js/3.1.9-1
/hmac-sha256.min.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/crypto-js/3.1.9-1
/enc-base64.min.js"></script>
<script>
 var hash = CryptoJS.HmacSHA256("Message", "secret");
 var hashInBase64 = CryptoJS.enc.Base64.stringify(hash);
 document.write(hashInBase64);
</script>

$s = hash_hmac('sha256', 'Message', 'secret', true);
echo base64_encode($s);

import java.crypto.Mac;
import java.crypto.spec.SecretKeySpec;
import org.apache.commons.codec.binary.Base64;
public class ApiSecurityExample {
 public static void main(String[] args) {
 try {
 String secret = "secret";
 String message = "Message";
 Mac sha256_HMAC = Mac.getInstance("HmacSHA256");
 SecretKeySpec secret_key = new SecretKeySpec(secret.getBytes(),"HmacSHA256");
 sha256_HMAC.init(secret_key);
 String hash = Base64.encodeBase64String(sha256_HMAC.doFinal(message.getBytes()));
 System.out.println(hash);
 }
 catch (Exception e){
 System.out.println("Error");
 }
 }
}

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.security.InvalidKeyException;
def hmac_sha256(String secretKey, String data) {
 try {
 Mac mac = Mac.getInstance("HmacSHA256")
 SecretKeySpec secretKeySpec = new SecretKeySpec(secretKey.getBytes(), "HmacSHA256")
 mac.init(secretKeySpec)
 byte[] digest = mac.doFinal(data.getBytes())
 return digest
 } catch (InvalidKeyException e) {
 throw new RuntimeException("Invalid key exception while converting to HMac SHA256")
 }
}
def hash = hmac_sha256("secret", "Message")
encodedData = hash.encodeBase64().toString()
log.info(encodedData)

Integration

During this phase, the merchant will use test user credentials to login in eSewa and process the transaction. Adequate balance will be updated to test the user account. The partner merchant will send request/post form request with various parameters. Some parameters are mandatory(i.e the parameters must be included) while some are optional. For end-to-end connection, some safety measures are applied while sending requests. The partner merchant should generate a signature using HMAC algorithm. Here's how the signature is to be generated and the generated signature should be sent along with the other request parameter.

For production please use following url:https://epay.esewa.com.np/api/epay/main/v2/form

<body>
 <form action="https://rc-epay.esewa.com.np/api/epay/main/v2/form" method="POST">
 <input type="text" id="amount" name="amount" value="100" required>
 <input type="text" id="tax_amount" name="tax_amount" value ="10" required>
 <input type="text" id="total_amount" name="total_amount" value="110" required>
 <input type="text" id="transaction_uuid" name="transaction_uuid"required>
 <input type="text" id="product_code" name="product_code" value ="EPAYTEST" required>
 <input type="text" id="product_service_charge" name="product_service_charge" value="0" required>
 <input type="text" id="product_delivery_charge" name="product_delivery_charge" value="0" required>
 <input type="text" id="success_url" name="success_url" value="https://esewa.com.np" required>
 <input type="text" id="failure_url" name="failure_url" value="https://google.com" required>
 <input type="text" id="signed_field_names" name="signed_field_names" value="total_amount,transaction_uuid,product_code" required>
 <input type="text" id="signature" name="signature" " required>
 <input value="Submit" type="submit">
 </form>
</body>

Demo

form-data:

{
"amount": "100",
"failure_url": "https://google.com",
"product_delivery_charge": "0",
"product_service_charge": "0",
"product_code": "EPAYTEST",
"signature": "YVweM7CgAtZW5tRKica/BIeYFvpSj09AaInsulqNKHk=",
"signed_field_names": "total_amount,transaction_uuid,product_code",
"success_url": "https://esewa.com.np",
"tax_amount": "10",
"total_amount": "110",
"transaction_uuid": "ab14a8f2b02c3"
}

Request Param Details:

Parameter Name	Description
amount	Amount of product
tax_amount	Tax amount applied on product
product_service_charge	product_service_charge Service charge by merchant on product
product_delivery_charge	Delivery charge by merchant on product
product_code	Merchant code provided by eSewa
total_amount	Total payment amount including tax, service and deliver charge. [i.e total_amount= amount+ tax_amount+ product_service_charge + product_delivery_charge ]
transaction_uuid	A unique ID of product, should be unique on every request.Supports alphanumeric and hyphen(-) only
success_url	a redirect URL of merchant application where customer will be redirected after SUCCESSFUL transaction
failure_url	a redirect URL of merchant application where customer will be redirected after FAILURE or PENDING transaction
signed_field_names	Unique field names to be sent which is used for generating signature
signature	hmac signature generated through above process.

All parameters are required i.e. values should not be null or empty. If tax_amount, product_service_charge & product_delivery_charge are not used for transaction then their respective values should be zero. In transaction_uuid , please use alphanumeric characters and hyphen(-) only

After Successful Payment

After successful payment, the user is redirected to the success URL (that you have sent) along with the response parameters encoded in Base64. Example (Decoded Response Body):

{
 "status": "COMPLETE",
 "signature": "ApAgFaOH8B1900oTI62Il9Gvl5C6Y87M0W6a1lRrK10=",
 "transaction_code": "0004T5I",
 "total_amount": 230,
 "transaction_uuid": "12-6-23",
 "product_code": "EPAYTEST",
 "success_url": "https://esewa.com.np",
 "signed_field_names": "transaction_code,status,total_amount,
transaction_uuid,product_code,signed_field_names"
}

Example (Response Body encoded in Base64)

ewogICAgInN0YXR1cyI6ICJDT01QTEVURSIsCiAgICAic2lnbmF0dXJlIjogIkFwQWdGYU9I
OEIxOTAwb1RJNjJJbDlHdmw1QzZZODdNMFc2YTFsUnJLMTA9IiwKICAgICJ0cmFuc2FjdGlv
bl9jb2RlIjogIjAwMDRUNUkiLAogICAgInRvdGFsX2Ftb3VudCI6IDIzMCwKICAgICJ0cmFu
c2FjdGlvbl91dWlkIjogIjEyLTYtMjMiLAogICAgInByb2R1Y3RfY29kZSI6ICJxZnhjaW5l
bWFzIiwKICAgICJzdWNjZXNzX3VybCI6ICJodHRwczovL2VzZXdhLmNvbS5ucCIsCiAgICAi
c2lnbmVkX2ZpZWxkX25hbWVzIjogInRyYW5zYWN0aW9uX2NvZGUsc3RhdHVzLHRvdGFsX2Ft
b3VudCx0cmFuc2FjdGlvbl91dWlkLHByb2R1Y3RfY29kZSxzaWduZWRfZmllbGRfbmFtZXMiCn0=

Make sure you verify the integrity of the response body by comparing the signature that we have sent with the signature that you generate. Signature should be generated the same way the request’s signature was generated.

URL

For testing:


https://uat.esewa.com.np/api/epay/transaction/status/?product_code=EPAYTEST&total_amount=100&transaction_uuid=123

For Production:


https://epay.esewa.com.np/api/epay/transaction/status/?product_code=EPAYTEST&total_amount=100&transaction_uuid=123

Request Parameter Description and Format

Response Types	Response Description	Response Format
PENDING	Payment Initiated but not been completed yet	{ "pid": "1301730000241234-0KSAXK-Both", "scd": "EPAYTEST", "totalAmount": 150.0, "status": "PENDING", "refId": null }
COMPLETE	Successful Payment	{ "pid": "1301040001194217-8MI83-Both", "scd": "EPAYTEST", "totalAmount": 150.0, "status": "COMPLETE", "refId": "0DAINTL" }
FULL_REFUND	Full Payment refunded to the customer	{ "pid": "1301250000708397", "scd": "EPAYTEST", "totalAmount": 50.0, "status": "FULL_REFUND", "refId": "0DA8G2E" }
PARTIAL_REFUND	Partial payment refunded to the customer	{ "pid": "Settle-Payment00050", "scd": "NP-ES-SUJAN-TEST", "totalAmount": 2.0, "status": "PARTIAL_REFUND", "refId": "0DDAU75 }
AMBIGIOUS	Payment is at hult state	{ "pid": "Settle-Payment00050", "scd": "NP-ES-SUJAN-TEST", "totalAmount": 2.0, "status": "AMBIGUOUS", "refId": "0DDAU75" }
NOT_FOUND	Payment terminated at eSewa: Session expired	{ "pid": "1301730000241234-0KSAXK-Both", "scd": "EPAYTEST", "totalAmount": 150.0, "status": "NOT_FOUND", "refId": null }
CANCELED	Canceled/Reversed from eSewa side	{ "pid": "1301730000241234-0KSAXK-Both", "scd": "EPAYTEST", "totalAmount": 150.0, "status": "CANCELED", "refId": 0DDAU75 }
Service is currently unavailable	Server connection timeout.	{ "code": 0, "error_message": "Service is currently unavailable" }

ePay is payment gateway which enables partner merchants to perform transaction initiated by customers having eSewa account in secure environment.

1. When user choses eSewa as online payment option from partner merchant application, then user is temporarily redirected to eSewa login page for payment.
2. User will provide valid credentials on login page.
3. By confirming the transaction, user is accepting the transaction details sent by partner merchants.
4. After each successful transaction, the user is redirected back to partner merchant’s success page. If transaction fails due to any reason (which includes user canceling transaction), the user is informed by appropriate failure message and redirected back to partner merchant’s failure page.
5. For every successful transaction, the merchant account is credited accordingly and notified via email/SMS regarding transaction.
6. Partner merchants need to invoke transaction verification request to verify potential fraudulent transactions occurred.
7. eSewa application will automatically notifies partner merchant with either success or failure response.

You will be provided with a technical document, test merchant service code, test user login credentials.

Yes, eSewa also provides payment integration in android and iOS applications. You can refer our documentation for mobile SDK integration for detail information about mobile integration.

On successful transaction the balance from eSewa user is transferred to merchant account and merchant can withdraw balance to respective bank account in free of cost.

eSewa provides 24 hours of customer support service. You can contact us in case of any inconvenience.

This may be the case of fraud transaction. For filtering fraud transactions, eSewa provides transaction verification system. So in this case service/product delivery must be stopped and one should implement the transaction verification process in eSewa ePay API as soon as possible.

If payment is not made within 15 minutes of login then transaction will be failed and user must reinitiate the transaction.

Yes, customer must be registered to eSewa for the completing the transaction.

Incase of epay ,the session will expire after some minutes.After that user will get error :``Your booking has expired. Please re-initiate the payment.``

Credentials & URLs

Each client will also receive a wallet on eSewa (Merchant wallet) from where they can find payments made for their products/services: Link For Production Mode: https://merchant.esewa.com.np To make payment with eSewa sdk. One must be a registered eSewa user. For testing phase, the client/merchant can use the following eSewa id and password: eSewa ID: 9806800001/2/3/4/5 Password: Nepal@123 MPIN: 1122 (for application only) Token:123456

Overview

Transaction Flow

System Interaction

HMAC/SHA256

Input

SecretKey:

Algorithm used for signature generation is SHA-256

Integration

Demo

Request Param Details:

Token

Status Check

Request Parameter Description and Format

FAQ

Credentials & URLs

ABOUT ESEWA

COMPANY

POLICIES

DOWNLOAD APP

Overview

Transaction Flow

System Interaction

HMAC/SHA256

Input

SecretKey:

Algorithm used for signature generation is SHA-256

Integration

Demo

Request Param Details:

Token

Status Check

Request Parameter Description and Format

FAQ

What is ePay?

What is the work-flow of eSewa ePay?

What are the item I will get for implementing eSewa ePay API?

Does eSewa provide payment integration in mobile applications?

What is the settlement mechanism from eSewa to Merchant Bank Account?

How eSewa provides support up on receiving any trouble because of ePay?

What is supposed to be done if the payment amount is confirmed by eSewa and transaction amount requested by Web application is not equal?

What is the time per session to make successful payment?

Should customer must have eSewa ID and its credential to do payment ?

What is the session expiry time for epay ?

Credentials & URLs

ABOUT ESEWA

COMPANY

POLICIES

DOWNLOAD APP