# Integration Modes

## Public Key Mode

Use for browser integrations with the JavaScript SDK.

- Required credential: `PONPONPAY_PUBLIC_KEY`
- SDK package: `@ponponpay/sdk`
- Import path: `@ponponpay/sdk/browser`
- Capabilities: exchange public key for short-lived session token, create browser orders, query browser order status, open checkout.
- Never use API keys in this mode.
- Configure the domain whitelist in the PonponPay merchant dashboard.

## API Key Mode

Use for server-side integrations with the PHP SDK.

- Required credential: `PONPONPAY_API_KEY`
- SDK package: `ponponpay/php-sdk`
- Capabilities: create orders, query orders, fetch payment methods, fetch merchant details, verify webhooks.
- Keep the API key in server-side environment variables only.

## Selection Guide

- Frontend-only app: use JavaScript SDK Public Key Mode.
- PHP backend app: use PHP SDK API Key Mode.
- Next.js app with API routes: use Public Key Mode for browser checkout, or use server routes with API Key Mode if order creation must stay backend-only.
- WordPress/Laravel/custom PHP: use PHP SDK.
- If the project has a database-backed order model, update the business order only after a verified webhook.

## Security Checklist

- No real credentials in committed files.
- No `PONPONPAY_API_KEY` in client-side code.
- Public Key domain whitelist configured.
- Webhook endpoint uses raw request body and signature verification.
- Payment success page does not mark orders paid without webhook confirmation.