Before you start
You need a Paymentsnp account and a server that can make HTTPS requests and keep a secret. Everything on this page happens in Test mode, where the Sandbox gateway simulates a success or a failure and no money moves.
| API base URL | https://api.paymentnp.com/v1 |
|---|---|
| Secret key | An np_test_ key with checkout:create and checkout:read |
| Amounts | Whole numbers in paisa: NPR 1,500.00 is 150000 |
| Checkout lifetime | One hour from creation |
| Confirmation | A signed payment.succeeded webhook, or the session status paid |
New accounts are reviewed by the Paymentsnp team before you can sign in, so create yours a little ahead of time. See account approval.
1. Get a test API key
In the dashboard, switch to Test, then:
Connect the Sandbox in Gateways
Open Gateways, connect Sandbox and enable it. You can also save your own eSewa, Khalti or Fonepay test credentials here; saving credentials does not switch a method on.
Add your site to allowed origins in Settings
Add your site, for example
https://shop.example.com, to allowed origins. Yoursuccess_urlandcancel_urlmust be on this list.Create a key in API keys
Create a key with
checkout:createandcheckout:readticked. Copy thenp_test_secret into your server config, for example asPAYMENTSNP_API_KEY.
2. Create a checkout from your server
Send the order ID and the amount in paisa. Use your order ID as the Idempotency-Key, so a retry after a timeout or a double click returns the same checkout instead of creating a second one.
curl -X POST https://api.paymentnp.com/v1/checkout/sessions \
-H "Authorization: Bearer $PAYMENTSNP_API_KEY" \
-H "Idempotency-Key: order-1001" \
-H "Content-Type: application/json" \
-d '{
"order_id": "order-1001",
"amount_minor": 150000,
"currency": "NPR",
"success_url": "https://shop.example.com/orders/1001",
"cancel_url": "https://shop.example.com/cart"
}'import { Paymentsnp } from "@paymentsnp/sdk";
const pnp = new Paymentsnp({ apiKey: process.env.PAYMENTSNP_API_KEY });
// NPR 1,500.00 = 150000 paisa
const session = await pnp.checkout.sessions.create(
{
order_id: "order-1001",
amount_minor: 150000,
currency: "NPR",
success_url: "https://shop.example.com/orders/1001",
cancel_url: "https://shop.example.com/cart",
},
{ idempotencyKey: "order-1001" },
);
// Redirect the customer to session.checkout_url<?php
$paymentsnp = new \Paymentsnp\PaymentsnpClient(getenv('PAYMENTSNP_API_KEY'));
// NPR 1,500.00 = 150000 paisa
$session = $paymentsnp->checkout->sessions->create([
'order_id' => 'order-1001',
'amount_minor' => 150000,
'currency' => 'NPR',
'success_url' => 'https://shop.example.com/orders/1001',
'cancel_url' => 'https://shop.example.com/cart',
], ['idempotency_key' => 'order-1001']);
header('Location: ' . $session['checkout_url']);import os
from paymentsnp import Paymentsnp
client = Paymentsnp(api_key=os.environ["PAYMENTSNP_API_KEY"])
# NPR 1,500.00 = 150000 paisa
session = client.checkout.sessions.create(
{
"order_id": "order-1001",
"amount_minor": 150000,
"currency": "NPR",
"success_url": "https://shop.example.com/orders/1001",
"cancel_url": "https://shop.example.com/cart",
},
idempotency_key="order-1001",
)
# Redirect the customer to session["checkout_url"]You get back 201 with an id, status: "open" and a checkout_url that is valid for one hour.
HTTP/1.1 201 Created
{
"id": "c1a94d07-…",
"order_id": "order-1001",
"status": "open",
"amount_minor": 150000,
"currency": "NPR",
"environment": "test",
"available_methods": ["esewa", "khalti", "fonepay"],
"expires_at": "2026-10-01T07:45:00.000Z",
"checkout_url": "https://paymentsnp.com/c/…",
"public_session_path": "/v1/checkout/public/…"
}Sending the same key with a different body returns 409 idempotency_conflict, so a bug that changes the amount cannot quietly create a second order.
3. Redirect, then confirm on your server
Redirect the customer to checkout_url. They pick eSewa, Khalti or Fonepay, pay on the provider's own page and come back to your success_url. In test mode, the Sandbox method lets you choose a success or a failure.
Webhook (recommended)
Add an HTTPS endpoint under Dashboard > Webhooks. Each event is a JSON POST with Paymentnp-Signature: t=<unix>,v1=<hex>, where v1 is the HMAC-SHA256 of t + "." + raw body made with your whsec_ secret.
- Verify the signature against the raw request body.
- Act on
payment.succeededand check the order ID and amount. - Store
event.idand skip any event you have already handled.
The webhooks guide has verification code for Node.js, PHP and Python.
API check
Call GET /v1/checkout/sessions/{id} with your key and fulfil only when status is paid.
curl https://api.paymentnp.com/v1/checkout/sessions/SESSION_ID \
-H "Authorization: Bearer $PAYMENTSNP_API_KEY"
# { "id": "...", "order_id": "order-1001", "status": "paid", ... }Popup instead of a redirect
To keep customers on your page, open the same checkout_url in a popup with checkout.js. Call it from a click so browsers allow the popup; if it is blocked, the customer continues in the same tab. If you list approved embed domains in Settings, your site must be one of them.
<script src="https://paymentsnp.com/checkout.js"></script>
<button onclick="Paymentnp.open({ checkoutUrl: 'CHECKOUT_URL' })">
Pay now
</button>The popup result is a hint for your page, not proof of payment. Confirm on your server exactly as in step 3. More on the checkout.js reference.
Go-live checklist
When test payments work end to end, move the same code to Live.
- Switch the dashboard to Live and connect your live eSewa, Khalti or Fonepay credentials.
- Create a live API key (
np_live_) and swap it into your server config. - Make sure your production site is in allowed origins.
- Add a live webhook endpoint and store its secret.
- Pay a real small amount end to end and check it appears under Payments and reaches your webhook.
The full checklist also covers provider testing for your own merchant credentials.
No-code and plug-in options
- WHMCS: download the module from Dashboard > Downloads, activate it, paste an API key with
checkout:create,checkout:readandpayments:read, and add your WHMCS site to allowed origins. No webhook needed. WHMCS guide. - Payment links: create a shareable link under Dashboard > Payment links with a fixed or customer-entered amount. Payment links.
- WooCommerce and Shopify: see the integrations.