Create a checkout session

Creates a new checkout session and returns a checkout_url to redirect your customer to.

The customer picks their preferred payment provider on the hosted page (or you pre-select one via provider). PayBridge notifies your returnUrl after the payment completes or fails.

Flow modes (set via flow):

• hosted (default) — render the PayBridge picker. If provider is set, that option is pre-selected, but the customer can still switch.
• redirect — skip the picker and 302 the customer straight to the chosen provider. Requires provider. On cancellation at the provider, the customer is sent to your cancelUrl (or returnUrl?status=cancelled if no cancelUrl is set).

Cancel handling: cancelUrl is optional. When omitted, cancellations fall back to returnUrl with ?session_id=...&status=cancelled appended. The hosted picker only renders a “Cancel” link when cancelUrl is explicitly provided.

Idempotency: Pass an Idempotency-Key header to safely retry failed requests without creating duplicate sessions. The key is scoped to your project and expires after 24 hours.

POST /v1/checkout

curl

cURL

curl -X POST https://api.paybridgenp.com/v1/checkout \
  -H "Authorization: Bearer pk_sandbox_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 10000,
    "currency": "NPR",
    "returnUrl": "https://yourapp.com/checkout/complete",
    "metadata": { "order_id": "order_123" }
  }'

201

{
  "id": "cs_01j9x2k3m4n5p6q7r8s9t0u1v2",
  "checkout_url": "https://checkout.paybridgenp.com/checkout/cs_01j9x2k3m4n5p6q7r8s9t0u1v2",
  "flow": "hosted",
  "provider": null,
  "expires_at": "2026-03-30T14:30:00.000Z"
}

Authorizations

Authorization · string · header · required

Your PayBridge API key. Obtain one from the dashboard under Settings → API Keys. Prefix: pk_sandbox_ for testing, pk_live_ for production.

Headers

Idempotency-Key · string

A unique string (UUID recommended) to make this request idempotent. Safe to retry on network failures.

Body

application/json

amount · integer · required

Payment amount in paisa. Must be an integer between 1,000 (Rs. 10) and 100,000,000 (Rs. 10,00,000). eSewa, Khalti, and Fonepay reject anything below Rs. 10.

Required range: 1000 <= x <= 100000000

Example:

10000

returnUrl · string<uri> · required

Your page URL. The customer is redirected here after payment (success or failure).

Example:

"https://yourapp.com/checkout/complete"

currency · enum<string> · default: NPR

Must be NPR. Other currencies are not yet supported.

Available options: NPR

cancelUrl · string<uri> | null

Where the customer lands when they cancel — both at the provider and via the "Cancel" link on the hosted picker. Optional. When omitted, cancellations fall back to returnUrl with ?session_id=...&status=cancelled appended, and the hosted picker hides its Cancel link entirely.

Example:

"https://yourapp.com/checkout/cancelled"

provider · enum<string>

Pre-select a provider. Omit to let the customer choose on the hosted page. Required when flow is redirect.

Available options: esewa, khalti, fonepay

flow · enum<string> · default: hosted

hosted (default) renders the PayBridge picker (provider pre-selected if set). redirect skips the picker and forwards straight to the provider — requires provider.

Available options: hosted, redirect

description · string | null

Human-readable purchase description (max 200 chars). Providers that support it — like Khalti's purchase_order_name — surface this on their hosted checkout page. Falls back to a generic placeholder when omitted.

Maximum string length: 200

Example:

"Order #1001"

metadata · object

Arbitrary key-value data (max 8 KB). Returned on the payment object and in webhook payloads.

Example:

{
  "order_id": "order_123",
  "customer_id": "cust_456"
}

customer · object

Optional customer details pre-filled on the checkout page.

Show child attributes

Response

201

application/json

Checkout session created.

id · string

Example:

"cs_01j9x2k3m4n5p6q7r8s9t0u1v2"

livemode · boolean

true when created with a live key, false for sandbox.

checkout_url · string<uri>

Redirect your customer to this URL to complete payment.

Example:

"https://checkout.paybridgenp.com/checkout/cs_01j9x2k3m4n5p6q7r8s9t0u1v2"

flow · enum<string>

Echoes the requested flow. Defaults to hosted when omitted on creation.

Available options: hosted, redirect

provider · enum<string> | null

Pre-selected provider, or null if the customer will pick on the hosted page.

Available options: esewa, khalti, fonepay

expires_at · string<date-time>