Create Checkout

POST/api/public/v1/payments

Creates a new payment checkout session and returns a hosted checkout_url you redirect your customer to. This is the primary entry point for collecting a payment. The session encodes the amount, currency, customer details, success and cancel URLs, and any merchant-defined metadata. The returned URL is valid for 30 minutes by default and can be opened in any modern browser on desktop or mobile. Use this endpoint whenever you need to take a one-off payment; for recurring billing, use the Subscription Checkout endpoint instead.

Request headers

Field	Type	Required	Description
Authorization	string	required	Your test or live API key. Example: `pg_live_xxx`
Content-Type	string	required	Must be application/json. Example: `application/json`

Request body

Field	Type	Required	Description
full_name	string	required	Customer's full name, shown on the checkout and on the receipt. Example: `Tasin Fahim`
email	string	required	Customer email. Receives the receipt and portal magic links. Example: `tasin@example.com`
amount	number	required	Amount in major units. Minimum 1, maximum 500000. Example: `1500`
currency	string	required	ISO 4217 currency code. Currently only BDT is supported. Example: `BDT`
metadata	object	optional	Arbitrary key/value pairs. Returned in webhooks. Max 20 keys, 500 chars each. Example: `{ "order_id": "ORD-1001" }`
success_url	string	required	HTTPS URL to redirect after successful payment. Receives invoice_id as a query param. Example: `https://yourstore.com/thank-you`
cancel_url	string	required	HTTPS URL to redirect if the customer abandons or cancels. Example: `https://yourstore.com/cancel`
webhook_url	string	optional	Per-checkout webhook override. Falls back to your dashboard webhook if omitted. Example: `https://yourstore.com/webhooks/naafipay`

Response

200 OK

1{
2  "invoice_id": "inv_01HZX5JM3W7QZK8YF7N9P0RTS2",
3  "checkout_url": "https://pay.naafipay.com/c/inv_01HZX5JM3W7QZK8YF7N9P0RTS2",
4  "qr_url": "https://pay.naafipay.com/qr/inv_01HZX5JM3W7QZK8YF7N9P0RTS2.png",
5  "amount": 1500,
6  "currency": "BDT",
7  "status": "pending",
8  "expires_at": "2026-05-30T14:32:00Z",
9  "created_at": "2026-05-30T14:02:00Z"
10}

TipAlways store the invoice_id

Save the returned invoice_id against your local order before redirecting the customer. You will need it to call Verify Payment from your success_url handler and to correlate webhook events.

Error codes

Field	Type	Required	Description
400	invalid_amount	optional	The amount is missing, zero, or above the maximum.
400	invalid_currency	optional	Currency is not BDT.
400	invalid_url	optional	success_url or cancel_url is not a valid HTTPS URL.
401	unauthorized	optional	API key is missing or invalid.
429	rate_limited	optional	You exceeded the write-rate limit. Retry after the Retry-After header value.

WarningDo not deliver goods on success_url alone

Always call POST /api/public/v1/verify-payment from your success_url handler before delivering the product. A user can navigate manually to the success URL without paying.