hamropay Docs

How Hamro Pay checkout works

Your customer starts on your website and pays on Hamro Pay’s hosted payment page. Your server creates the session and confirms the payment before you fulfill the order.

From checkout to a confirmed payment

Read from top to bottom. Each column represents one part of the integration; arrows show the requests and responses between them.

Sequence diagram: your website asks your server to start checkout; your server creates a signed session with Hamro Pay and returns checkout fields; the browser submits them to hosted checkout; the customer returns; your server queries payment status. An optional signed webhook can arrive independently.

The customer’s return and the payment confirmation are separate events. The lifecycle below explains each exchange in text.

Open full-size diagram Download PNG

On a small screen, scroll the diagram sideways or open it at full size.

Who does what

Customer’s browser

Your website

Shows the order and submits the checkout form. This is where your customer starts and returns.

Merchant backend

Your server

Creates signed sessions, keeps credentials private, and checks payments against saved orders.

Payment service

Hamro Pay API

Creates payment sessions, provides transaction status, and sends configured webhook updates.

Payment page

Hosted checkout

Lets your customer choose a payment method and complete the payment on Hamro Pay.

The checkout lifecycle

Diagram Steps 1–4

Create the session

The customer starts checkout on your website. Your server reads the saved order, signs a Create Session request, and sends it to Hamro Pay. The API returns session_id and token. Your server gives the browser only the fields needed for checkout.

Create your first session

Diagram Step 5

Open the payment page

The browser sends a POST form to the checkout gateway. The form contains the merchant ID, session ID, checkout token, and your order’s transaction ID. On the hosted page, your customer chooses a payment method and completes checkout.

Build the checkout form

Diagram Step 6

Bring the customer back

Hamro Pay returns the customer to the successUrl or failureUrl you supplied when creating the session. The URL includes MerchantTxnId, which lets you look up the saved order. A return to the success page is not proof of payment.

Understand return URLs

Diagram Steps 7–8

Verify, then fulfill

Your server calls Get Transaction using the saved merchant and transaction IDs. Check for COMPLETED and match the returned order ID and amount to your records. Mark the order as paid and fulfill it once. Keep pending, processing, or failed orders unpaid.

Verify a payment

Built for platforms that host merchants

If your platform hosts e-commerce stores or other services, it can earn a commission on each payment. The customer pays the selling merchant through your platform. Hamro Pay allocates your platform’s configured share to its merchant account and the remainder to the seller’s own account.

One payment. Two account allocations.

Illustrative 3% platform commission

Customer pays

NPR 1,000.00

Full order amount

Platform receives

NPR 30.00

3% to the platform merchant account

Selling merchant receives

NPR 970.00

Remainder to the seller’s own account

This example shows the commission allocation only and excludes any payment processing fees. The 3% is an example platform rate.

The checkout flow above stays the same. When creating the session, use the seller’s merchantId and add clientCommissionConfig with your platform’s commissionMerchantId and commissionPercentage.

Explore Payments for Platforms

What if the customer closes the page?

Your server can still receive a payment update through a webhook. Register an HTTPS endpoint with Hamro Pay and verify each notification with your separate webhook signing secret.

Webhooks arrive independently of the browser redirect. An update may arrive before or after the customer returns, and your handler must safely handle repeated updates. Verify the signature, match the payment to the saved order, and fulfill only once.

Keep the payment decision on your server

The return page is for the customer. A verified transaction check or validated webhook is for your order records. Never fulfill an order based only on a URL, browser-submitted amount, or session status.

Set up verified webhooks

Ready to connect your website?

Continue to the checkout quickstart.

Next: checkout quickstart