Framework guides

Mount one secure Cipay buyer handler in Next.js, Hono, Express, or Astro.

Every integration wraps the same createCipayBuyerHandler. Framework code should authenticate the application session, apply a rate limit, and pass a standard Web Request to the handler.

Next.js

Use an App Router Route Handler.

Hono

Pass context.req.raw directly.

Express

Convert Node requests with a bounded body.

Astro

Return the Web Response from an endpoint.

What every integration must do

Keep credentials on the server

Read CIPAY_SANDBOX_API_KEY and CIPAY_STOREFRONT_LOCATOR from server-only configuration.

Rate limit first

Apply an application or edge rate limit before reading a body or calling Cipay.

Resolve a verified session

Map your authenticated application user to a stored Cipay customer ID. Ignore customer identity in browser input.

Mount the fixed handler

Pass only the intended Cipay route to the standard Request → Response handler.

Verify webhooks separately

Use the exact raw webhook body and persist each event ID before business effects.

Choose your framework

All four guides expose the same browser API. The only difference is how the framework gives a standard Web Request to the handler.

Framework	Server boundary	Request adaptation	Client UI
Next.js	App Router catch-all Route Handler	None	`CipayProvider` and React components
Hono	`app.all` route	None; use `context.req.raw`	React components or plain fetch
Express	Router middleware	Convert Node request and response; cap the body	React components or plain fetch
Astro	Server endpoint	None	Server-rendered Astro or a React island

Each guide separates configuration, authentication, route mounting, client usage, and verification, then links one complete assembled example.