API overview

REST and JSON over HTTPS, one currency and integer amounts. This page covers how keys, scopes, retries, errors and limits work, and lists every route an API key can call.

Every request
POST /v1/checkout/sessions HTTP/1.1
Host: api.paymentnp.com
Authorization: Bearer np_test_...
Idempotency-Key: order-1001
Content-Type: application/json

{ "order_id": "order-1001", "amount_minor": 150000,
  "currency": "NPR", ... }
Bearer key, JSON body, amounts in paisa. Idempotency-Key on checkout creation and refunds.

Basics

Base URLhttps://api.paymentnp.com/v1
FormatREST over HTTPS. JSON request and response bodies with snake_case field names.
CurrencyNPR only.
AmountsInteger paisa in every *_minor field. Rs 1 is 100 paisa, so NPR 1,500.00 is 150000.
DatesISO 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.

The eight API key scopes
ScopeAllowsTypical use
checkout:createCreate and expire checkout sessionsYour checkout server
checkout:readRead a checkout session and its statusYour checkout server, order status checks
payments:readList and read verified payments, summaries and recorded refundsBack office, WHMCS module
refunds:writeRecord a refund you made in the provider panelBack office
invoices:readList and read invoices and their PDFsAccounting sync
invoices:writeCreate, edit, finalize, send, mark paid, void and duplicate invoicesBilling systems
reconciliation:readRead settlement records and the reconciliation reportFinance tools
reconciliation:writeImport settlement records, one at a time or up to 500 at onceFinance tools

Key controls

ExpiryOptional. An expired key returns 401 api_key_expired.
IP allowlistOptional, up to 20 IP addresses or CIDR ranges. Other addresses get 403 api_key_ip_denied.
Rate limitPer key, per minute. 600 by default, up to 6,000.
RollingRoll 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.
StorageThe 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": "…"
  }
}
Common error codes
CodeStatusMeaning
unauthorized401Missing, wrong or revoked key.
api_key_expired401The key passed its expiry date. Create or roll a key.
insufficient_scope403The key lacks the scope this route needs.
api_key_ip_denied403The request came from an IP outside the key's allowlist.
environment_mismatch403A test key asked for live data, or the other way round.
payment_pending409A payment attempt on this order is still unresolved, so a second one cannot start.
idempotency_conflict409The same Idempotency-Key was sent with a different body.
rate_limited429Too many requests. Wait for the seconds in the Retry-After header.
provider_unavailable503The method cannot be used right now, for example NEPALPAY QR, which checkout does not offer yet.

Rate limits

Per IP120 requests per minute across the API.
Per API keyThe key's own limit (600 per minute by default) applies instead of the per-IP limit on API-key routes.
Invalid keysAt most 30 invalid API keys per IP per minute.
When limited429 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

Checkout session status values
StatusMeaning
openCreated and waiting for the customer. Sessions last one hour.
processingA payment attempt is in progress with a provider.
paidThe provider confirmed the exact amount. Safe to fulfil.
manually_confirmedA team member recorded the payment from a provider reference. Not verified by the provider; a later verified success moves it to paid.
expiredThe session ended without a payment.
cancelledThe 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.

Core API-key routes
RouteMethodScopeWhat it does
/v1/checkout/sessionsPOSTcheckout:createCreate a checkout. Needs Idempotency-Key.
/v1/checkout/sessions/:idGETcheckout:readRead a session and its status.
/v1/checkout/sessions/:id/expirePOSTcheckout:createStop new payment attempts.
/v1/paymentsGETpayments:readVerified payments, filterable by provider, search and dates.
/v1/payments/:idGETpayments:readOne payment with its provider transaction ID.
/v1/payments/:id/refundsPOSTrefunds:writeRecord a refund made in the provider panel.
/v1/invoicesGETinvoices:readInvoices by status, with totals.
/v1/invoicesPOSTinvoices:writeCreate a draft invoice.
/v1/invoices/:id/finalizePOSTinvoices:writeNumber a draft and open it for payment.
/v1/invoices/:id/sendPOSTinvoices:writeEmail the invoice and its link, and/or send an SMS notice (no link).
/v1/reconciliation/import/bulkPOSTreconciliation:writeImport up to 500 settlement rows.
/v1/reconciliation/reportGETreconciliation:readVerified payments against settlements, 7, 30 or 90 days.
More API-key routes
RouteMethodScopeWhat it does
/v1/payments/summaryGETpayments:readVerified totals and pending attempts. Never a balance.
/v1/payments/:id/refundsGETpayments:readRefunds recorded for one payment.
/v1/invoices/:idGETinvoices:readOne invoice.
/v1/invoices/:id/pdfGETinvoices:readThe invoice as a PDF.
/v1/invoices/:idPATCHinvoices:writeReplace a draft.
/v1/invoices/:id/mark-paidPOSTinvoices:writeMark paid outside Paymentsnp, with a note.
/v1/invoices/:id/voidPOSTinvoices:writeVoid an invoice.
/v1/invoices/:id/uncollectiblePOSTinvoices:writeMark an invoice uncollectible.
/v1/invoices/:id/duplicatePOSTinvoices:writeCopy an invoice into a new draft.
/v1/reconciliationGETreconciliation:readImported settlement records.
/v1/reconciliation/importPOSTreconciliation:writeImport 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 UIapi.paymentnp.com/docs
OpenAPI JSONhttps://api.paymentnp.com/openapi.json
HealthGET 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).