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

# Payhere plugin

> Payhere is a Stripe-backed payment links platform. This plugin reads the account user, company and 30-day stats, lists customers, payments, plans and subscriptions, reads a customer with their payment history, issues full or partial refunds, and receives HMAC-verified payment and subscription webhooks.

Use **Payhere** through Corsair: one client, typed API calls, and incoming webhooks.

Authenticate with the API key from the integrations section of the merchants admin; the plugin sends it as an Authorization Bearer token. Every list endpoint pages with page and per\_page (default 20, maximum 100) and answers \{ data, meta } where meta.next\_page is the next page number.
Webhook deliveries are signed in the X-Signature header: HMAC-SHA1 hex of the raw body with the shared secret from the merchants admin. Store that secret with keys.set\_webhook\_signature (or set webhookSecret on the plugin) so deliveries can be verified. Events include payment.success, payment.failed and subscription.cancelled.
The plugin covers nine read and refund operations. Creating plans and cancelling subscriptions (POST /api/v1/plans, DELETE /api/v1/subscriptions/:id) are not wrapped yet.
Every operation is described in the official docs: [https://developers.payhere.co/docs/api-auth](https://developers.payhere.co/docs/api-auth)

**What you get:**

* 9 typed API operations
* 1 incoming webhook event types

## Setup

**1. Install**

```bash npm theme={null}
npm install corsair @corsair-dev/payhere better-sqlite3
npm install --save-dev @types/better-sqlite3
```

```bash yarn theme={null}
yarn add corsair @corsair-dev/payhere better-sqlite3
yarn add --dev @types/better-sqlite3
```

```bash pnpm theme={null}
pnpm install corsair @corsair-dev/payhere better-sqlite3
pnpm install --save-dev @types/better-sqlite3
```

```bash bun theme={null}
bun add corsair @corsair-dev/payhere better-sqlite3
bun add --dev @types/better-sqlite3
```

**2. Add the plugin**

```ts corsair.ts theme={null}
import Database from 'better-sqlite3';
import { createCorsair } from 'corsair';
import { payhere } from '@corsair-dev/payhere';

export const corsair = createCorsair({
	plugins: [
		payhere(),
	],
	database: new Database('corsair.db'),
	kek: process.env.CORSAIR_KEK!,
	multiTenancy: true,
	hub: {
		projectApiKey: process.env.CORSAIR_API_KEY!,
		signingSecret: process.env.CORSAIR_SIGNING_SECRET!,
	},
});
```

With `multiTenancy: true`, scope calls with `corsair.withTenant(id)`. See [Quick start](https://docs.corsair.dev/quick-start.md) for KEK + Hub keys, and [Multi-tenancy](https://docs.corsair.dev/concepts/multi-tenancy.md) for account isolation.

**3. Choose authentication**

> [tab] API Key (Recommended)
>
> Store the Payhere API key before the first call: `pnpm corsair setup --plugin=payhere --tenant=acme api_key=<your-key>` (leave out `--tenant` without `multiTenancy`), or pass it as `key` in the plugin options. With Hub, each tenant enters their own key on the connect page. See [API key auth](https://docs.corsair.dev/concepts/api-key).
>
> ```ts theme={null}
> payhere()
> ```
>
> More: [API Key](https://docs.corsair.dev/concepts/api-key)

**4. Connect a tenant**

Mint a connect link and send the tenant to it. Hub hosts the page and delivers the result to your app — see [Connect / OAuth](https://docs.corsair.dev/management/connect).

```ts theme={null}
const { connectUrl } = await corsair.manage.connect.createLink({
	plugin: 'payhere',
	tenantId: 'acme',
});
// redirect the user's browser to connectUrl
```

## Example API calls

**Read a customer with their history**

```ts theme={null}
const tenant = corsair.withTenant('acme');
await tenant.payhere.api.customers.get({ customerId: 989899294 });
```

**Refund a payment**

```ts theme={null}
const tenant = corsair.withTenant('acme');
await tenant.payhere.api.refunds.create({ payment_id: 373, amount: 0.5, reason: 'requested_by_customer' });
```

See the full list on the [API](https://docs.corsair.dev/plugins/payhere/api.md) page.

## Webhooks

This plugin registers **1** webhook event type. Configure the provider to POST to your Corsair HTTP handler, then use `webhookHooks` on the plugin factory.

See [Webhooks](https://docs.corsair.dev/plugins/payhere/webhooks.md) for every event path and payload shape, and [Webhooks concept](https://docs.corsair.dev/concepts/webhooks.md) for routing.

## What's next

> [card] [API reference](https://docs.corsair.dev/plugins/payhere/api.md)
>
> Every `payhere.api.*` operation with input and output types.

> [card] [Webhooks](https://docs.corsair.dev/plugins/payhere/webhooks.md)
>
> Event paths, payloads, and `webhookHooks` examples.

> [card] [Connect / OAuth](https://docs.corsair.dev/management/connect)
>
> createLink, Hub delivery, and tenant connect flows.

> [card] [Use with agents](https://docs.corsair.dev/mcp-adapters/mcp-adapters)
>
> Expose this plugin's operations as MCP tools.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.