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.
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.
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 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 for every merchant partner will be provided from eSewa
For UAT, SecretKey will be 8gBm/:&EnhH.1/q( Input should be text type.)
The generated signature should be in base-64 output type. For eg:
4Ov7pCI1zIOdwtV2BRMUNjz1upIlT/COTxfLhWvVurE=
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
{
"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"
}
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 request is being sent, user is redirected to login page where users input eSewaId and Password. A 6-digit verification token is sent to user mobile(SMS or email) depends upon eSewaId used by user. For now, only for testing purpose token is 123456 to remove the hassle to obtain token each time after login.
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"
}
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.
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.
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
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" } |
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