Overview

The eSewa ePay system enables partner merchant to perform transaction and receive money from customer having eSewa account in 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.

Implementation

eSewa ePay system integration on partner merchant's application is the process of implementing eSewa as payment option. The integration process itself is performed in two phases, namely :

Development & Staging Environment

The development and testing activities are carried out on URL: https://uat.esewa.com.np This phase is intended to test process flow, transactions and other integration results. A test eSewa Id with password will be provided to the partner merchant to complete the transaction. Note: Test server may be taken off-line for maintenance or other technical reasons, during which users will receive “Service Temporarily Unavailable” message or any other message. In such case, please try again later or contact eSewa staff regarding issue. The primary objective of this stage are:

  • 1. Whether merchant requests are getting posted onto eSewa ePay system or not.

  • 2. Whether merchant is getting response of either a successful or failure transaction on their site.

  • 3. Implementation and testing of verification process.

Production Environment

The production transaction is carried out on URL: https://esewa.com.np . After successful testing phase, the partner merchant will be provided with merchant code for production environment credentials on request. Partner merchant’s have to modify the request URL and point toward production server and use production environment merchant credentials. Then, partner merchant will be able to start accepting payments using eSewa ePay payment gateway.

Integration

Pre-requisite

It is required for merchant to provide eSewa with two email ids. Those emails will be used for creating merchant and end user in test environment. During this phase, merchant will use test user credentials to login in eSewa and process the transaction. Adequate balance will be updated to test user account.

Payment

{URI: /epay/main } The partner merchant will send transaction request to URL provided by eSewa with various parameters. Some of those parameters are required while others are optional. All parameters must not be empty or null. Optional parameters not used should have default value set. Esewa will perform validation to check whether request parameters value are correct and in format. Validation failure will result to failure response and message, ending transaction process.

Request Details

Parameter Name Description
amt Amount of product or item or ticket etc
txAmt Tax amount on product or item or ticket etc
psc Service charge by merchant on product or item or ticket etc
pdc Delivery charge by merchant on product or item or ticket etc
tAmt Total payment amount including tax, service and deliver charge. [i.e tAmt = amt + txAmt + psc + tAmt]
pid A unique ID of product or item or ticket etc(supports only alphanumeric and hyphen-)
scd Merchant code provided by eSewa
su Success URL: a redirect URL of merchant application where customer will be redirected after SUCCESSFUL transaction
fu Failure URL: a redirect URL of merchant application where customer will be redirected after FAILURE or PENDING transaction

All parameters are required i.e. values should not be null or empty. If txAmt, psc & pdc are not used for transaction then their respective values should be zero.

Redirect URI su and fu must start with http:// or https:// protocol.

For every successful transaction, eSewa will redirect user to success URI provided by partner merchant. The redirected URI will contain response query string.

For Successful Payment

Response Snippet

http://merchant.com.np/page/esewa_payment_success?q=su&oid=ee2c3ca1-696b-4cc5-a6be-2c40d929d453&amt=100&refId=000AE01

Parameter Name Description
oid Product ID (pid) used on payment request
amt Total payment amount (tAmt)
refId A unique payment reference code generated by eSewa

Payment Verification

{URI: /epay/transrec }

eSewa provides Fraud Management Filter using Transaction Verification Process, which make it easier for partner merchant to detect and respond to fraudulent transaction. Partner merchant need to implement the filter before they take effect. Transaction verification process provide you filter that identify potentially fraudulent transactions and screen against data such as the value of transaction amount. Transaction verification process checks for payment characteristics that may indicate fraudulent activity. You set up Transaction Verification Process to provide the tightest control possible over payments so that you can deny payments that are likely to result in fraudulent transactions and accept payments that are not typically a problem. Payments that require further investigation or intervention, such as comparing prior orders or contacting customer for more information, can be denied or put on hold or pended for review. The following flow chart, conceptually shows how transaction verification works: The transaction verification process will tally the difference between transaction amount and total purchase price of the product or services generated at merchant’s end. If the transaction amount of product is less than a specified amount in merchant’s end (i.e. stored price in server) the verification process will end and transaction will be failed. The partner merchant have to send transaction verification request for each successful transactions with various parameters. In amount field merchant have to send the amount generated at their respective server not the amount eSewa sends as response after each successful transaction. All parameters are required. The partner merchant will receive either Success or failure message on response. The Success response message means transaction with given parameters is valid in eSewa while failure means it is void/invalid.

Request Details

Parameter Name Description
amt Total payment amount of product or service
scd Merchant code provided by eSewa
pid A unique ID of product or item or ticket etc generated by merchant for payment
rid A unique payment reference code from eSewa generated on SUCCESSFUL transaction
Response Snippet

For Successful Payment Verification
<response>
    <response_code>Success</response_code>
</response> 
For Failed Payment Verification
<response>
    <response_code>failure</response_code>
</response> 

Status Check

An API for client enquiry when a transaction is initiated and no response is provided from eSewa or received by Merchant. API parameters are product code, pid and amount client requests for transaction status with pid , scd , amount and esewa will respond with successful transaction code and status if failed status only.

URL

https://uat.esewa.com.np/api/epay/txn_status/v2?pid=1301730000241234-0KSAXK-Both&totalAmount=150&scd=EPAYTEST
 

Request Parameter Description

Parameter Description
pid A unique ID of product or item or ticket etc generated by merchant for payment
scd Merchant code provided by eSewa for Merchant
totalAmount Paying Amount
Response Format:

{"pid": "17890", "scd": "EPAYTEST", "totalAmount": 675.0, "status": "PENDING" }

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" }


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


FAQ

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 minutes.After that user will get error :``Your booking has expired. Please re-initiate the payment.``