Basics
| Base URL | https://api.paymentnp.com/v1 |
|---|---|
| Format | REST over HTTPS. JSON request and response bodies with snake_case field names. |
| Currency | NPR only. |
| Amounts | Integer paisa in every *_minor field. Rs 1 is 100 paisa, so NPR 1,500.00 is 150000. |
| Dates | ISO 8601 timestamps. Date filters such as from and to are Nepal calendar days. |
Never use floating-point maths for money. The SDKs ship toPaisa and formatNpr helpers that work on strings and integers only.
Authentication
Send your secret key as a bearer token. Keys start with np_test_ or np_live_, and the prefix decides the environment: a test key never sees live data, and a live key never sees test data.
curl https://api.paymentnp.com/v1/payments?limit=10 \
-H "Authorization: Bearer $PAYMENTSNP_API_KEY"Keys are created under Dashboard > API keys by owners, administrators and developers. Keep them on your server. The dashboard itself uses a separate signed-in session, and its routes (CSV exports, webhook settings, key management) are not open to API keys.
Scopes
A key carries only the scopes you tick. Give each system the smallest set it needs; a missing scope returns 403 insufficient_scope.
| Scope | Allows | Typical use |
|---|---|---|
checkout:create | Create and expire checkout sessions | Your checkout server |
checkout:read | Read a checkout session and its status | Your checkout server, order status checks |
payments:read | List and read verified payments, summaries and recorded refunds | Back office, WHMCS module |
refunds:write | Record a refund you made in the provider panel | Back office |
invoices:read | List and read invoices and their PDFs | Accounting sync |
invoices:write | Create, edit, finalize, send, mark paid, void and duplicate invoices | Billing systems |
reconciliation:read | Read settlement records and the reconciliation report | Finance tools |
reconciliation:write | Import settlement records, one at a time or up to 500 at once | Finance tools |
Key controls
| Expiry | Optional. An expired key returns 401 api_key_expired. |
|---|---|
| IP allowlist | Optional, up to 20 IP addresses or CIDR ranges. Other addresses get 403 api_key_ip_denied. |
| Rate limit | Per key, per minute. 600 by default, up to 6,000. |
| Rolling | Roll a key to get a new secret while the old one keeps working for a grace period of 1 hour, 24 hours or 7 days. |
| Storage | The secret is shown once and stored only as a SHA-256 hash. |
Idempotency
An Idempotency-Key header is required on checkout creation, on recording a refund and on payment-link checkouts. Use a value tied to the thing you are creating, such as your order ID.
- Same key and same body: the original response is replayed, so you get the same checkout.
- Same key and a different body:
409 idempotency_conflict. - Keys may use letters, digits and
. _ : -, up to 120 characters.
Other writes, such as invoice and reconciliation calls, are not deduplicated by the API. The SDKs retry them only when the request never reached the server.
Errors
Every error has the same body. Log the request_id; it is the quickest way to trace a request.
HTTP/1.1 409 Conflict
{
"error": {
"code": "idempotency_conflict",
"message": "…",
"request_id": "…"
}
}| Code | Status | Meaning |
|---|---|---|
unauthorized | 401 | Missing, wrong or revoked key. |
api_key_expired | 401 | The key passed its expiry date. Create or roll a key. |
insufficient_scope | 403 | The key lacks the scope this route needs. |
api_key_ip_denied | 403 | The request came from an IP outside the key's allowlist. |
environment_mismatch | 403 | A test key asked for live data, or the other way round. |
payment_pending | 409 | A payment attempt on this order is still unresolved, so a second one cannot start. |
idempotency_conflict | 409 | The same Idempotency-Key was sent with a different body. |
rate_limited | 429 | Too many requests. Wait for the seconds in the Retry-After header. |
provider_unavailable | 503 | The method cannot be used right now, for example NEPALPAY QR, which checkout does not offer yet. |
Rate limits
| Per IP | 120 requests per minute across the API. |
|---|---|
| Per API key | The key's own limit (600 per minute by default) applies instead of the per-IP limit on API-key routes. |
| Invalid keys | At most 30 invalid API keys per IP per minute. |
| When limited | 429 rate_limited with a Retry-After header in seconds. |
Sign-in, registration, password reset and public checkout pages have their own, tighter limits. A header that only looks like a key never lifts the per-IP limit.
Session and payment states
| Status | Meaning |
|---|---|
open | Created and waiting for the customer. Sessions last one hour. |
processing | A payment attempt is in progress with a provider. |
paid | The provider confirmed the exact amount. Safe to fulfil. |
manually_confirmed | A team member recorded the payment from a provider reference. Not verified by the provider; a later verified success moves it to paid. |
expired | The session ended without a payment. |
cancelled | The session was stopped. |
GET /v1/payments lists verified payments only. Attempts that are still pending, or whose provider answer is unknown, are not payments yet. An unknown answer is treated as possibly paid and blocks a second payment on the same order until it is resolved.
Endpoints
Paths are relative to https://api.paymentnp.com. The SDKs cover every route below with the same method names in TypeScript, PHP and Python.
| Route | Method | Scope | What it does |
|---|---|---|---|
/v1/checkout/sessions | POST | checkout:create | Create a checkout. Needs Idempotency-Key. |
/v1/checkout/sessions/:id | GET | checkout:read | Read a session and its status. |
/v1/checkout/sessions/:id/expire | POST | checkout:create | Stop new payment attempts. |
/v1/payments | GET | payments:read | Verified payments, filterable by provider, search and dates. |
/v1/payments/:id | GET | payments:read | One payment with its provider transaction ID. |
/v1/payments/:id/refunds | POST | refunds:write | Record a refund made in the provider panel. |
/v1/invoices | GET | invoices:read | Invoices by status, with totals. |
/v1/invoices | POST | invoices:write | Create a draft invoice. |
/v1/invoices/:id/finalize | POST | invoices:write | Number a draft and open it for payment. |
/v1/invoices/:id/send | POST | invoices:write | Email the invoice and its link, and/or send an SMS notice (no link). |
/v1/reconciliation/import/bulk | POST | reconciliation:write | Import up to 500 settlement rows. |
/v1/reconciliation/report | GET | reconciliation:read | Verified payments against settlements, 7, 30 or 90 days. |
| Route | Method | Scope | What it does |
|---|---|---|---|
/v1/payments/summary | GET | payments:read | Verified totals and pending attempts. Never a balance. |
/v1/payments/:id/refunds | GET | payments:read | Refunds recorded for one payment. |
/v1/invoices/:id | GET | invoices:read | One invoice. |
/v1/invoices/:id/pdf | GET | invoices:read | The invoice as a PDF. |
/v1/invoices/:id | PATCH | invoices:write | Replace a draft. |
/v1/invoices/:id/mark-paid | POST | invoices:write | Mark paid outside Paymentsnp, with a note. |
/v1/invoices/:id/void | POST | invoices:write | Void an invoice. |
/v1/invoices/:id/uncollectible | POST | invoices:write | Mark an invoice uncollectible. |
/v1/invoices/:id/duplicate | POST | invoices:write | Copy an invoice into a new draft. |
/v1/reconciliation | GET | reconciliation:read | Imported settlement records. |
/v1/reconciliation/import | POST | reconciliation:write | Import one settlement record. |
There are no payout or balance endpoints: Paymentsnp never holds funds. Refunds are recorded, not sent; you refund the customer in the provider's own panel. See reconciliation for the settlement side.
OpenAPI, Swagger and health
| Swagger UI | api.paymentnp.com/docs |
|---|---|
| OpenAPI JSON | https://api.paymentnp.com/openapi.json |
| Health | GET https://api.paymentnp.com/v1/health |
The Swagger reference is generated from the API and is public. The full written guide, with integration walkthroughs, is in the dashboard at developer guide (sign-in required).