logo

hamro pay

Checkout

Zero Checkout Integration Cost

Integrate Hamro Pay Checkout in minutes.
No setup fee. No integration cost.

Reliable Simple Secure
Hamro Pay Checkout MacBook and iPhone Mockup
Free

Zero Setup Cost

No setup or monthly fees. Pay only when you receive payments.

Secure by Design

We follow industry standard security practices to keep your transactions safe.

Instant Settlement

Receive payments instantly in your Hamro Pay wallet.

Easy Integration

Simple REST API with clear documentation.

Getting Started

Checkout Integration Process

Follow the steps below to create your test merchant account, get integration credentials, configure the webhook, integrate the APIs, and test the Checkout flow.

Merchant Onboarding

1. Create and Verify Your Test Merchant Account

Register your merchant account through the UAT Merchant Portal to start your checkout integration.

Use verification OTP: 000000
Complete required KYB verification: Provide business registration details in the portal to activate test checkout capabilities.
Important: Your merchant account must be verified before proceeding with integration and generating live API keys.
Documentation

API Integration

Integrate Hamro Pay Checkout into your application with full API specifications, signature generation algorithms, and webhooks.

UAT Base API: https://uat-payclient.hamropatro.com/
Steps & Chapters
Need Assistance?

Our developer engineering team is available to assist with custom sandbox onboarding and technical integration.

Overview & Architecture

1. How does hamropay checkout works

Checkout is a low-code payment integration that redirects customers to a Hamro pay hosted payment page. It securely supports one-time payment.

Hight level sequence of web checkout using Hamro Pay

Sequence for Hamro Pay web checkout

Sequence for hamropay web checkout

  • merchant-website : Your website where user lands to
  • merchant-service : Your backend service which your service uses
  • hamropay-server : Hamropay backend API server
  • hamropay-checkout-gateway : Hamropay payment web view where the payment is redirected to

1.1. Checkout life cycle

Flow for Hamro Pay checkout

Flow for Hamro Pay checkout

1
Create Session / Payment Intent Request :
  • The merchant's backend initiates a request to the HamroPay platform to generate a session.
  • The request includes secret keys and client credentials provided by the HamroPay platform.
  • Upon receiving the request, HamroPay verifies the credentials and creates a session or payment intent for the particular transaction.
  • Build the params object (see Params) required by your web client for posting form data to initiate the Hamro Pay Payment Page (see 4.2 Checkout Proceed API).
  • The response contains necessary data to build form data that needs to be posted to Hamro Pay web client.
2
Post Form Data to HamroPay Checkout Client :

The merchant's frontend receives the session/payment intent data. Using this data, the frontend submits the required form to the HamroPay checkout client.

3
Redirect to HamroPay Web Portal / Checkout Portal :
  • User is redirected to Hamro Pay checkout website / portal with form data posted by the client.
  • Customer completes the checkout / payment process on the HamroPay portal.
4
Return to Merchant Site :

Upon successful payment, users are redirected back to the merchant's site. The redirect URL is pre-configured during the payment intent creation (see 6. Webhook (Optional)).

1.2 Transaction limit per transaction:

User Checkout Limit Minimum Limit Maximum Limit
VERIFIED Rs. 10 Rs. 50,000
NOT_VERIFIED 0 (NOT ALLOWED) 0 (NOT ALLOWED)
Authentication

2. Headers

Every hamropay api request should include certain headers to work. It is mandatory to include all these headers unless described explicitly in the API description.

Following are three headers that the client needs to pass while sending every requests:

  • Signature : The signature string generated using the client secret. The signature should be a Base64 string of HMAC512 message output.
  • Client Id : The unique id that will be generated and given by the Hamropay team.
  • Client-Api-Key : The secret api key that will be provided by the Hamropay team.

Headers Example with Key And Values :

Header Key Value Example Description
Signature base64stringrepresentation== Base64 HMAC-SHA512 signature string
Client-Id 123123123132-asda-asda-asda-asdasdasd Unique ID provided by Hamropay team
Client-Api-Key 8c9e2ea0-4eb5-11f1-baa3-de257371874e Secret API Key provided by Hamropay team
headers.http
Signature: base64stringrepresentation==
Client-Id: 123123123132-asda-asda-asda-asdasdasd
Client-Api-Key: 8c9e2ea0-4eb5-11f1-baa3-de257371874e
Content-Type: application/json
Security & Cryptography

3. Signature Generation

This section describes how the signature string should be generated in general, for the values required for generating the signature please consult every api section found below.

Signature must be included in the header section of the request. To generate a signature we need the signature string (described in the individual API section) and client secret.

The client secret used for generating the string will be provided by the Hamro Pay team and shared ONLY between the client and Hamro Pay Checkout API.

Security Notice: Please keep your client secret securely, so we recommend it to be known by your backend only with proper measures taken to protect it.

The signature should be a Base64 string of HMAC512 message output.

Psudo Code Example:

pseudo-signature.txt
client_secret = 'abcdefg'

signature_message_string = field1 + ',' + field2 + ',' + field3 + ',' + field4.. fieldn 
(String separated by comma). 

final_signature_string = toBase64 ( HmacSHA512Digest ( signature_message_string , client_secret ) )

*(Values separated by comma as a string). Messages are different according to APIs.*
What field's to be used for generating the signature_message are defined in the every API sections.

3.1. Sample Code For Base64 Signature Generation

signature.js
const crypto = require('crypto');

/**
 * Generate HMAC-SHA512 signature in Base64
 * @param {string} message - Comma-separated fields
 * @param {string} secret - Client secret provided by Hamro Pay
 * @returns {string} Base64 encoded signature
 */
function signHMAC(message, secret) {
  try {
    const hmac = crypto.createHmac('sha512', secret);
    hmac.update(message, 'utf8');
    return hmac.digest('base64');
  } catch (error) {
    throw new Error('HMAC signature generation failed: ' + error.message);
  }
}

// Example usage:
const signature = signHMAC("2500.00,NPR,PN_-Nd99TBnAlBjCgl8ef_b,ORD-12345,usr_sec_991823ab", "YOUR_CLIENT_SECRET");
console.log("Signature:", signature);
REST Endpoints

4. Checkout API

4.1. Create Session API

Intended API User: Merchant backend

Fields required for generating Signature string:

  • amount
  • currency
  • merchantId
  • merchantTxnId
  • userSecret

Use these fields for signature string generation i.e values of the fields combined with ',' to form a single string and see Signature Generation section to see how to generate this.

create-session-signature.txt
initial_signature_string = amount+','+currency+','+merchantId+','+merchantTxnId+','+userSecret
final_signature_string = toBase64 ( HmacSHA512DigestOf ( initial_signature_string , using_secret ) )

Request :

Fields Data Type Description
merchantId * String Unique id for merchant
merchantTxnId * String Merchant Transaction ID (Length less or equal to 25 chars)
amount * Double Amount in Rupees. Double value (e.g. 23.77)
currency * String Currency of the transaction (e.g. "NPR")
userSecret * String Client user secret
successUrl * String Url to redirect after the transaction is successfully completed.
failureUrl * String Url to redirect after the transaction is failed or canceled.
remarks String Remarks for the transaction.
clientCommissionConfig JSON Object If applicable for client. @see Client Commission Config
productList Array of JSON Object List of product for checkout page @see Product List Sample
Client Commission Config
commission-config.json
"clientCommissionConfig": {
    "commissionMerchantId": "8c9e2ea0-4eb5-11f1-baa3-de257371874e1",
    "commissionPercentage": 3.56
}
Product List Sample
product-list.json
"productList" : [
  {
    "name": "shirt",
    "imageUrl": "https://testUrl.jpg",
    "description": "This is shirt",
    "price": 99.99, // Amount in Rs. for render purpose so Rs.99.99 should be 99.99
    "quantity": 1
  }
]

Response :

Fields Data Type Description
signature String Base64 Signature representation
merchantTxnId String Merchant Transaction ID
trackingId String Tracking ID for the transaction
amount Double Amount in Rupees
status String Status of the transaction
client_id String Client ID
client_api_key String Client API key
merchantId String Merchant ID
Request / Response Samples :
create-session-request.json
{
  "merchantId": "PN_-Nd99TBnAlBjCgl8ef_b",
  "merchantTxnId": "ORD-2026-08912",
  "amount": 2500.00,
  "currency": "NPR",
  "userSecret": "usr_sec_991823ab",
  "successUrl": "https://merchant.com/checkout/success",
  "failureUrl": "https://merchant.com/checkout/failure",
  "remarks": "Order payment #8912",
  "clientCommissionConfig": {
    "commissionMerchantId": "8c9e2ea0-4eb5-11f1-baa3-de257371874e1",
    "commissionPercentage": 3.56
  },
  "productList": [
    {
      "name": "Casual Cotton Shirt",
      "imageUrl": "https://merchant.com/images/shirt.jpg",
      "description": "Premium casual wear shirt",
      "price": 2500.00,
      "quantity": 1
    }
  ]
}

4.2 Checkout Proceed API

Intended API User: Merchant frontend

Make a POST request with following parameters to the provided GATEWAY_URL with Content-Type as application/x-www-form-urlencoded.

Params :

Fields Data Type Description
merchant_id * String Unique id of the merchant provided by the Hamro Pay team.
session_id * String Session ID obtained from Create Session API
token * String Token obtained from Create Session API
merchant_transaction_id * String Unique transaction id generated by merchant. Length should be less than or equal to 25 characters.
remarks String Remarks about the transaction. Length should be less than or equal to 250 characters.
phone_number String Phone number of the Hamro Pay user if available. [OPTIONAL]
Js Sample Checkout-Form using params above
checkout-form.js
const params = {
  merchant_id: "Your merchant id",
  session_id: "Session ID",
  token: "Your Token",
  merchant_transaction_id: "ORD-2026-08912", // <= 25 chars
  remarks: "Remarks (upto 250 chars)",
  phone_number: "98XXXXXXXX" // optional
};

const form = document.createElement("form");
form.method = "POST";
form.action = path; // GATEWAY_URL
form.enctype = "application/x-www-form-urlencoded";

for (const key in params) {
  if (params.hasOwnProperty(key)) {
    const hiddenField = document.createElement("input");
    hiddenField.type = "hidden";
    hiddenField.id = key;
    hiddenField.name = key;
    hiddenField.value = params[key];
    form.appendChild(hiddenField);
  }
}

document.body.appendChild(form);
form.submit();

Hosted Checkout UI Previews

When your application posts form data to GATEWAY_URL, customers are redirected to the responsive Hamro Pay payment gateway.

1. Web Portal Checkout UI (Desktop & Tablet)
Hamro Pay Web Portal Checkout UI Mockup
2. Mobile Web Checkout UI
Hamro Pay Mobile Checkout UI Mockup

4.3. Get Transaction API

Intended API User: Merchant backend

Fields required for generating Signature string:

  • merchantTxnId
  • merchantId
  • client_id
  • clientApiKey

Use these fields for signature string generation i.e values of the fields combined with ',' to form a single string and see Signature Generation section to see how to generate this.

get-transaction-signature.txt
initial_signature_string = merchantTxnId+','+merchantId+','+client_id+','+clientApiKey
final_signature_string = toBase64 ( HmacSHA512DigestOf ( initial_signature_string , using_secret ) )

Request :

Fields Data Type Description
merchantId * String Unique id merchant
merchantTxnId * String Merchant Transaction ID from previous requests

Response :

Fields Data Type Description
merchantTransactionId String Merchant Transaction ID
status String Status of the transaction. ( PENDING , PROCESSING , FAILED , COMPLETED )
amount Double Amount in Rupees.
remarks String Remarks of the transaction.
message String Message about the transaction.
Request / Response Samples :
get-transaction-completed.json
// Request
{
    "merchantId" : "PN_-Nd99TBnAlBjCgl8ef_b",
    "merchantTxnId" : "bdg68smvsyg"
}

// Response
{
    "merchantTransactionId": "bdg68smvsyg",
    "trackingId": "9d7ebc60-ba76-11ee-a642-ba34db130c51",
    "status": "COMPLETED",
    "amount": 14.5,
    "remarks": "This is remarks",
    "message": "SUCCESS"
}

Once the transaction is successful or failed, Hamropay provides the response of the transaction through the Client’s response url provided during Create Session API Or through the webhook . The response is sent to the provided response url after the transaction is successful/Failed.

Call-back URLs

5. Success / Failed Redirection

After the transaction, HamroPay will redirect to the provided success or failure URL.

Regarding the Success Redirection URL

If the URL provided is https://something.com/success, HamroPay will redirects to client appending the MerchantTxnId as below:

success-redirect.url
https://something.com/success?MerchantTxnId=123213

Where, MerchantTxnId represents the actual transaction ID, which Client can utilize to confirm the transaction from their end.

Regarding the Failure Redirection URL

If the URL provided is https://something.com/failure, HamroPay will redirects to client appending the MerchantTxnId as below:

failure-redirect.url
https://something.com/failure?MerchantTxnId=123213

Where, MerchantTxnId represents the actual transaction ID, which Client can utilize to confirm the transaction from their end.

Asynchronous Notifications

6. Webhook (Optional)

Merchants / Clients will receive a webhook to their provided POST REQUEST URL (endpoint) from hamro pay after the Checkout transaction is successful or failed. The webhook can be used to trigger the actual transaction without having to poll for the transaction status.

6.1 Using Hamro Pay webhook

  1. Integration Setup : To begin, the client integrates their application with Hamro Pay's payment system. This involves providing a callback URL, typically a POST endpoint, where Hamro Pay will send webhook notifications which is a json body regarding payment details.
  2. Webhook Configuration : Once integrated, Hamro Pay configures its system to send payment webhook notifications to the provided URL whenever a payment status changes, such as success or failure.
  3. Handling Webhook Requests : The client's server needs to implement an endpoint to receive and process webhook requests. This endpoint should be capable of handling POST requests and parsing the incoming data.
  4. Processing Payment Status : Upon receiving a webhook notification, the client's server extracts relevant information from the payload, such as transaction ID, status, and any associated metadata.
  5. Handling Success or Failure : Depending on the received status, the client's application can take appropriate actions. For instance, if the payment was successful, it can update the user's account or trigger a confirmation message. If the payment failed, it can initiate a refund process or notify the user about the issue.
  6. Signature Verification (Optional but Recommended) : To ensure the authenticity of webhook requests and prevent unauthorized access or tampering, HamroPay can include a signature along with the payload. The client's server then verifies this signature to confirm that the request indeed originates from HamroPay.

Webhook Body:

These are the json body fields you will receive in request from hamropay backend to your provided endpoint.

Fields Data Type Description
merchantTxnId String MerchantTransactionId generated from client, can be used to fetch transaction with merchantId
merchantId String For Reconciliation purpose
amount double Transaction amount in Rs.
status String Status of the transaction. (PENDING, PROCESSING, FAILED, COMPLETED)
metadata map<string,string> Same Extra data returned, that you send while creating payment intent
Json Representation
webhook-payload.json
// HEADER
// Signature: <<Signature String generated from hamropay>>

{
  "merchantTxnId": "Txn Id used for reconciliation purposed initially from client",
  "merchantId": "your merchant Id",
  "amount": 9.99, // in Rs.
  "status": "COMPLETED OR FAILED", // either or,
  "metadata": {"field1":"fieldValue1","field2":"fieldValue2"}
}

6.2 Webhook Verification

You will get a webhook request containing the signature in the header. The signature string is available in header in key Signature i.e header.get("Signature"). The {{merchantWebHookSigningSecret}} will be provided by Hamro Pay team.

The {merchantWebHookSigningSecret} is only used to validate the webhook request and for nothing else.
verify-webhook.js
// Use the following fields from the body, to generate the signature string:
// Seperated by commas
var signatureString = merchantTxnId +','+ merchantId +','+ status +','+ amount;

var signatureFromHeader = header.get("Signature");
var signatureGenFromBodyInBase64 = Base64( HMAC.signHMAC(signatureString , {{merchantWebHookSigningSecret}}) );

var isValid = signatureFromHeader.equals(signatureGenFromBodyInBase64);

You can 3. Signature Generation to see code sample how to generate signature string using the fields merchantTxnId +','+ merchantId +','+ status +','+ amount

Reference

7. Code with Description

  • OK OR ACTIVE = 0
  • CANCELED = 1
  • UNKNOWN = 2
  • INVALID_ARGUMENT = 3
  • TIME_OUT = 4
  • NOT_FOUND OR SUSPENDED = 5
  • ALREADY_EXISTS = 6
  • PERMISSION_DENIED = 7
  • LIMIT_EXCEEDED = 8
  • FAILED_PRECONDITION = 9
  • ABORTED = 10
  • OUT_OF_RANGE = 11
  • UNIMPLEMENTED = 12
  • INTERNAL = 13
  • UNAVAILABLE = 14
  • DATA_LOSS = 15
  • UNAUTHENTICATED = 16

Ready to start accepting payments?

Integrate once and get access to a seamless payment experience for your users.

Hamro Pay Support

Grievance officer

Follow Us

© 2026 HamroPay. All Rights Reserved.