curl

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

import { PayBridgeNP } from "@paybridge-np/sdk";

const paybridgenp = new PayBridgeNP({ apiKey: "sk_test_your_key" });

const session = await paybridgenp.checkout.create({
  amount: 10000,
  currency: "NPR",
  returnUrl: "https://yourapp.com/checkout/complete",
  metadata: { order_id: "order_123" },
});

// Redirect customer
redirect(session.checkout_url);

$response = $paybridgenp->post('https://api.paybridgenp.com/v1/checkout', [
  'headers' => ['Authorization' => 'Bearer sk_test_your_key'],
  'json' => [
    'amount' => 10000,
    'currency' => 'NPR',
    'returnUrl' => 'https://yourapp.com/checkout/complete',
    'metadata' => ['order_id' => 'order_123'],
  ],
]);
$session = json_decode($response->getBody(), true);
header('Location: ' . $session['checkout_url']);

import requests

url = "https://api.paybridgenp.com/v1/checkout"

payload = {
    "amount": 10000,
    "returnUrl": "https://yourapp.com/checkout/complete",
    "currency": "NPR",
    "cancelUrl": "https://yourapp.com/checkout/cancelled",
    "flow": "hosted",
    "description": "Order #1001",
    "metadata": {
        "order_id": "order_123",
        "customer_id": "cust_456"
    },
    "customer": {
        "name": "Aarav Sharma",
        "email": "aarav@example.com",
        "phone": "9801234567",
        "address": {
            "line1": "Thamel Road",
            "city": "Kathmandu",
            "line2": "Apt 4B",
            "state": "Bagmati",
            "postalCode": "44600",
            "country": "Nepal"
        }
    },
    "collectAddress": False
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.paybridgenp.com/v1/checkout"

	payload := strings.NewReader("{\n  \"amount\": 10000,\n  \"returnUrl\": \"https://yourapp.com/checkout/complete\",\n  \"currency\": \"NPR\",\n  \"cancelUrl\": \"https://yourapp.com/checkout/cancelled\",\n  \"flow\": \"hosted\",\n  \"description\": \"Order #1001\",\n  \"metadata\": {\n    \"order_id\": \"order_123\",\n    \"customer_id\": \"cust_456\"\n  },\n  \"customer\": {\n    \"name\": \"Aarav Sharma\",\n    \"email\": \"aarav@example.com\",\n    \"phone\": \"9801234567\",\n    \"address\": {\n      \"line1\": \"Thamel Road\",\n      \"city\": \"Kathmandu\",\n      \"line2\": \"Apt 4B\",\n      \"state\": \"Bagmati\",\n      \"postalCode\": \"44600\",\n      \"country\": \"Nepal\"\n    }\n  },\n  \"collectAddress\": false\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.paybridgenp.com/v1/checkout")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"amount\": 10000,\n  \"returnUrl\": \"https://yourapp.com/checkout/complete\",\n  \"currency\": \"NPR\",\n  \"cancelUrl\": \"https://yourapp.com/checkout/cancelled\",\n  \"flow\": \"hosted\",\n  \"description\": \"Order #1001\",\n  \"metadata\": {\n    \"order_id\": \"order_123\",\n    \"customer_id\": \"cust_456\"\n  },\n  \"customer\": {\n    \"name\": \"Aarav Sharma\",\n    \"email\": \"aarav@example.com\",\n    \"phone\": \"9801234567\",\n    \"address\": {\n      \"line1\": \"Thamel Road\",\n      \"city\": \"Kathmandu\",\n      \"line2\": \"Apt 4B\",\n      \"state\": \"Bagmati\",\n      \"postalCode\": \"44600\",\n      \"country\": \"Nepal\"\n    }\n  },\n  \"collectAddress\": false\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.paybridgenp.com/v1/checkout")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"amount\": 10000,\n  \"returnUrl\": \"https://yourapp.com/checkout/complete\",\n  \"currency\": \"NPR\",\n  \"cancelUrl\": \"https://yourapp.com/checkout/cancelled\",\n  \"flow\": \"hosted\",\n  \"description\": \"Order #1001\",\n  \"metadata\": {\n    \"order_id\": \"order_123\",\n    \"customer_id\": \"cust_456\"\n  },\n  \"customer\": {\n    \"name\": \"Aarav Sharma\",\n    \"email\": \"aarav@example.com\",\n    \"phone\": \"9801234567\",\n    \"address\": {\n      \"line1\": \"Thamel Road\",\n      \"city\": \"Kathmandu\",\n      \"line2\": \"Apt 4B\",\n      \"state\": \"Bagmati\",\n      \"postalCode\": \"44600\",\n      \"country\": \"Nepal\"\n    }\n  },\n  \"collectAddress\": false\n}"

response = http.request(request)
puts response.read_body

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

{
  "error": {
    "message": "<string>",
    "code": "<string>",
    "request_id": "req_2Je91NlWKuXkdXUJOK9gaHNW",
    "suspension": {
      "suspended_at": "2023-11-07T05:31:56Z",
      "reason": "<string>"
    },
    "pause": {
      "paused_at": "2023-11-07T05:31:56Z",
      "reason": "<string>"
    }
  }
}

{
  "error": {
    "message": "<string>",
    "code": "<string>",
    "request_id": "req_2Je91NlWKuXkdXUJOK9gaHNW",
    "suspension": {
      "suspended_at": "2023-11-07T05:31:56Z",
      "reason": "<string>"
    },
    "pause": {
      "paused_at": "2023-11-07T05:31:56Z",
      "reason": "<string>"
    }
  }
}

Checkout

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). PayBridgeNP notifies your returnUrl after the payment completes or fails.

Flow modes (set via flow):

hosted (default) - render the PayBridgeNP 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

checkout

curl

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

import { PayBridgeNP } from "@paybridge-np/sdk";

const paybridgenp = new PayBridgeNP({ apiKey: "sk_test_your_key" });

const session = await paybridgenp.checkout.create({
  amount: 10000,
  currency: "NPR",
  returnUrl: "https://yourapp.com/checkout/complete",
  metadata: { order_id: "order_123" },
});

// Redirect customer
redirect(session.checkout_url);

$response = $paybridgenp->post('https://api.paybridgenp.com/v1/checkout', [
  'headers' => ['Authorization' => 'Bearer sk_test_your_key'],
  'json' => [
    'amount' => 10000,
    'currency' => 'NPR',
    'returnUrl' => 'https://yourapp.com/checkout/complete',
    'metadata' => ['order_id' => 'order_123'],
  ],
]);
$session = json_decode($response->getBody(), true);
header('Location: ' . $session['checkout_url']);

import requests

url = "https://api.paybridgenp.com/v1/checkout"

payload = {
    "amount": 10000,
    "returnUrl": "https://yourapp.com/checkout/complete",
    "currency": "NPR",
    "cancelUrl": "https://yourapp.com/checkout/cancelled",
    "flow": "hosted",
    "description": "Order #1001",
    "metadata": {
        "order_id": "order_123",
        "customer_id": "cust_456"
    },
    "customer": {
        "name": "Aarav Sharma",
        "email": "aarav@example.com",
        "phone": "9801234567",
        "address": {
            "line1": "Thamel Road",
            "city": "Kathmandu",
            "line2": "Apt 4B",
            "state": "Bagmati",
            "postalCode": "44600",
            "country": "Nepal"
        }
    },
    "collectAddress": False
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.paybridgenp.com/v1/checkout"

	payload := strings.NewReader("{\n  \"amount\": 10000,\n  \"returnUrl\": \"https://yourapp.com/checkout/complete\",\n  \"currency\": \"NPR\",\n  \"cancelUrl\": \"https://yourapp.com/checkout/cancelled\",\n  \"flow\": \"hosted\",\n  \"description\": \"Order #1001\",\n  \"metadata\": {\n    \"order_id\": \"order_123\",\n    \"customer_id\": \"cust_456\"\n  },\n  \"customer\": {\n    \"name\": \"Aarav Sharma\",\n    \"email\": \"aarav@example.com\",\n    \"phone\": \"9801234567\",\n    \"address\": {\n      \"line1\": \"Thamel Road\",\n      \"city\": \"Kathmandu\",\n      \"line2\": \"Apt 4B\",\n      \"state\": \"Bagmati\",\n      \"postalCode\": \"44600\",\n      \"country\": \"Nepal\"\n    }\n  },\n  \"collectAddress\": false\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.paybridgenp.com/v1/checkout")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"amount\": 10000,\n  \"returnUrl\": \"https://yourapp.com/checkout/complete\",\n  \"currency\": \"NPR\",\n  \"cancelUrl\": \"https://yourapp.com/checkout/cancelled\",\n  \"flow\": \"hosted\",\n  \"description\": \"Order #1001\",\n  \"metadata\": {\n    \"order_id\": \"order_123\",\n    \"customer_id\": \"cust_456\"\n  },\n  \"customer\": {\n    \"name\": \"Aarav Sharma\",\n    \"email\": \"aarav@example.com\",\n    \"phone\": \"9801234567\",\n    \"address\": {\n      \"line1\": \"Thamel Road\",\n      \"city\": \"Kathmandu\",\n      \"line2\": \"Apt 4B\",\n      \"state\": \"Bagmati\",\n      \"postalCode\": \"44600\",\n      \"country\": \"Nepal\"\n    }\n  },\n  \"collectAddress\": false\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.paybridgenp.com/v1/checkout")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"amount\": 10000,\n  \"returnUrl\": \"https://yourapp.com/checkout/complete\",\n  \"currency\": \"NPR\",\n  \"cancelUrl\": \"https://yourapp.com/checkout/cancelled\",\n  \"flow\": \"hosted\",\n  \"description\": \"Order #1001\",\n  \"metadata\": {\n    \"order_id\": \"order_123\",\n    \"customer_id\": \"cust_456\"\n  },\n  \"customer\": {\n    \"name\": \"Aarav Sharma\",\n    \"email\": \"aarav@example.com\",\n    \"phone\": \"9801234567\",\n    \"address\": {\n      \"line1\": \"Thamel Road\",\n      \"city\": \"Kathmandu\",\n      \"line2\": \"Apt 4B\",\n      \"state\": \"Bagmati\",\n      \"postalCode\": \"44600\",\n      \"country\": \"Nepal\"\n    }\n  },\n  \"collectAddress\": false\n}"

response = http.request(request)
puts response.read_body

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

{
  "error": {
    "message": "<string>",
    "code": "<string>",
    "request_id": "req_2Je91NlWKuXkdXUJOK9gaHNW",
    "suspension": {
      "suspended_at": "2023-11-07T05:31:56Z",
      "reason": "<string>"
    },
    "pause": {
      "paused_at": "2023-11-07T05:31:56Z",
      "reason": "<string>"
    }
  }
}

{
  "error": {
    "message": "<string>",
    "code": "<string>",
    "request_id": "req_2Je91NlWKuXkdXUJOK9gaHNW",
    "suspension": {
      "suspended_at": "2023-11-07T05:31:56Z",
      "reason": "<string>"
    },
    "pause": {
      "paused_at": "2023-11-07T05:31:56Z",
      "reason": "<string>"
    }
  }
}

Authorizations

Authorization

string

header

required

Your PayBridgeNP API key. Obtain one from the dashboard under Settings → API Keys. Prefix: sk_test_ for testing, sk_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. 1,000,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 PayBridgeNP 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 | null

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 | null

Optional customer details pre-filled on the checkout page.

Show child attributes

collectAddress

boolean

default:false

When true, the hosted checkout page asks the customer for a shipping address (street and city required) before payment. The collected address is included as customer_address in webhook event payloads - null otherwise.

Response

Checkout session created.

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>

Overview

Checkout

Payment Links

Payments

Refunds

Webhooks

Account

Billing

Providers

SMS

Create a checkout session

Authorizations

Headers

Body

Response