> ## Documentation Index
> Fetch the complete documentation index at: https://docs.paybridgenp.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Use hosted checkout for a new payment integration unless the user explicitly needs an SDK or Direct QR flow.
> Keep secret API keys on the server. Never place an sk_test_ or sk_live_ key in browser or mobile code.
> Never treat a browser return URL as proof of payment. Verify a signed webhook and confirm status, amount, and currency on the server before fulfillment.
> Fonepay has no sandbox. A Fonepay payment made from a sandbox project uses the merchant's real Fonepay account and moves real money within the documented caps.
> Do not recommend direct integration with Mobile SDK device endpoints. Use the PayBridgeNP Mobile SDK and the merchant-facing session creation API.

# API overview

> Learn the PayBridgeNP API conventions for authentication, amounts, pagination, retries, and versioning.

The PayBridgeNP API uses JSON over HTTPS. All merchant API requests start with this base URL:

```text theme={null}
https://api.paybridgenp.com/v1
```

<CardGroup cols={2}>
  <Card title="Authenticate on the server" icon="key" href="/api-reference/authentication">
    Send a secret API key as a Bearer token. Never expose an `sk_` key in browser or mobile code.
  </Card>

  <Card title="Make retries safe" icon="rotate" href="/guides/idempotency">
    Add an `Idempotency-Key` to create and update requests that might be retried.
  </Card>

  <Card title="Handle errors consistently" icon="triangle-exclamation" href="/api-reference/errors">
    Branch on the stable error `type` and `code`, and retain the request ID for support.
  </Card>

  <Card title="Check service status" icon="signal" href="https://status.paybridgenp.com">
    See current PayBridgeNP and provider availability before investigating an integration failure.
  </Card>
</CardGroup>

## Request conventions

| Convention     | What to send                                             |
| -------------- | -------------------------------------------------------- |
| Authentication | `Authorization: Bearer sk_test_...` or `sk_live_...`     |
| Content type   | `Content-Type: application/json` for JSON request bodies |
| Amounts        | Integer paisa. `10000` means NPR 100.00                  |
| Currency       | `NPR` unless an endpoint says otherwise                  |
| Dates          | ISO 8601 timestamps in UTC                               |
| Idempotency    | A stable `Idempotency-Key` for a single logical write    |

<Warning>
  A test key does not make every provider payment fake. eSewa and Khalti use test environments, but Fonepay has no sandbox. Fonepay payments from a sandbox project use your real Fonepay account and move real money within the documented caps.
</Warning>

## Pagination

List endpoints use offset pagination:

```bash theme={null}
curl "https://api.paybridgenp.com/v1/payments?limit=50&offset=0" \
  -H "Authorization: Bearer sk_test_your_key"
```

Paginated responses include a `data` array and a `meta` object with `total`, `limit`, and `offset`. Increase `offset` by `limit` until you have read the required range. Do not assume that a short page is permanent when new records can be created during pagination.

## Rate limits and retries

Rate-limited API responses return `429`. Read `Retry-After` before retrying. Public API responses may also include:

* `X-RateLimit-Limit`
* `X-RateLimit-Remaining`
* `X-RateLimit-Reset`

Retry temporary `429` and `5xx` responses with bounded exponential backoff. Use an idempotency key so retrying a write does not create a second resource.

## Request IDs

Every response includes `X-Request-Id`. Error responses repeat the same value as `error.request_id`. Record it with your application logs and include it when contacting support.

## Versioning

The current API is namespaced under `/v1`. Additive response fields and new enum values may appear without changing the URL, so ignore fields you do not use and handle unknown enum values safely. Breaking request or response changes require a new version or a documented deprecation period.

## Start building

<CardGroup cols={2}>
  <Card title="Create a checkout" icon="cart-shopping" href="/api-reference/checkout/create-session">
    Create a hosted payment session and redirect the customer to its checkout URL.
  </Card>

  <Card title="Confirm a payment" icon="badge-check" href="/guides/confirming-payments">
    Verify a signed webhook and match status, amount, and currency before fulfillment.
  </Card>
</CardGroup>