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",
    "embedOrigin": "https://yourshop.com",
    "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  \"embedOrigin\": \"https://yourshop.com\",\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  \"embedOrigin\": \"https://yourshop.com\",\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  \"embedOrigin\": \"https://yourshop.com\",\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",
    "embedOrigin": "https://yourshop.com",
    "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  \"embedOrigin\": \"https://yourshop.com\",\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  \"embedOrigin\": \"https://yourshop.com\",\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  \"embedOrigin\": \"https://yourshop.com\",\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"

embedOrigin

string<uri> | null

Opt this session into Embedded Checkout: render the payment overlay on your own page (cart totals, your own checkout page) instead of redirecting. Must be an origin already registered under Project -> Embed domains for this mode, or the request fails with a 400 so you find out at create time. Requires a Growth plan or higher, and flow must be hosted. The session's checkout URL then renders inside the overlay on that origin; after the provider round-trip the customer returns to your returnUrl with session_id, status and (on success) payment_id appended - render your confirmation from those, or fetch the session. When the customer is offered a PayBridgeNP ID save prompt, they see our hosted success page first and continue to your returnUrl from there. (The automatic overlay reopen on return belongs to payment-button sessions, whose script on your page carries the state to do it.)

Example:

"https://yourshop.com"

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