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

# Next.js adapter

> Proxy SDK requests through your own backend

The `unitpayHandler` from `@unitpay/react/next` lets you route SDK calls through your Next.js backend instead of calling the UnitPay API directly. The secret key stays server-side, and requests never leave your domain.

## Usage

Add a catch-all route handler:

```ts theme={null}
// app/api/unitpay/[...path]/route.ts
import { unitpayHandler } from '@unitpay/react/next';

const handler = unitpayHandler({
  apiKey: process.env.UNITPAY_SECRET_KEY!,
  apiBaseUrl: 'https://api.useunitpay.com/v1',
  allowedOrigins: [process.env.NEXT_PUBLIC_APP_URL!],
  getCustomerId: async (request) => resolveCustomerFromSession(request),
});

export {
  handler as GET,
  handler as POST,
  handler as PUT,
  handler as PATCH,
  handler as DELETE,
};
```

Then point the provider at the proxy instead of the API:

```tsx theme={null}
import { UnitPayProvider } from '@unitpay/react';

<UnitPayProvider config={{ customerId: 'cus_...', proxyBaseUrl: '/api/unitpay' }}>
  <App />
</UnitPayProvider>
```

## Parameters

<ParamField body="apiKey" type="string" required>
  Your UnitPay secret key. Read it from a server-only environment variable — never expose it to the browser.
</ParamField>

<ParamField body="getCustomerId" type="(request: Request) => Promise<string | null>" required>
  Resolve the authenticated customer for the incoming request (from your session/auth). Return `null` for an unauthenticated request — the handler responds `401`.
</ParamField>

<ParamField body="apiBaseUrl" type="string">
  UnitPay API base URL. Defaults to `https://api.useunitpay.com/v1`.
</ParamField>

<ParamField body="allowedOrigins" type="string[] | '*'">
  Origins permitted to call the proxy. Requests with an `Origin` outside this list are rejected with `403`. Pass `'*'` to disable the check (not recommended in production). When omitted, the `Origin` check is skipped.
</ParamField>

<ParamField body="maxBodyBytes" type="number">
  Maximum request body size. Defaults to 1 MB; larger bodies are rejected with `413`.
</ParamField>

<Note>
  **Security defaults:** disallowed methods → `405`; off-allowlist `Origin` → `403`; oversized
  bodies → `413`. Only `GET`, `POST`, `PUT`, `PATCH`, and `DELETE` are forwarded.
</Note>