---
name: ponponpay-sdk-integration
description: Use when a user wants to integrate PonponPay payments into an existing application with the official SDKs. Covers PHP API Key Mode for server-side order creation and webhooks, JavaScript Public Key Mode for browser checkout, framework detection, environment setup, safe secret handling, and validation.
metadata:
  short-description: Integrate PonponPay SDKs into an app
---

# PonponPay SDK Integration

Use this skill when the user asks to add PonponPay payments, checkout, crypto payment acceptance, USDT/USDC payments, webhook handling, or SDK setup to an existing codebase.

## Core Rules

- Never put an API Key in browser code, committed source files, screenshots, logs, or examples.
- Use **Public Key Mode** for browser/frontend order creation with the JavaScript SDK.
- Use **API Key Mode** for server-side order creation, order queries, payment methods, merchant details, and webhook verification.
- Prefer official SDKs over hand-written API calls.
- Add only minimal integration code that matches the host project patterns.
- Add `.env.example` entries, but never write real secrets into `.env` unless the user explicitly provides local-only values.
- Use the merchant backend webhook as the source of truth for marking business orders paid.
- Keep generated order IDs globally unique and idempotent.

## Workflow

1. Inspect the repository to identify framework, package manager, backend language, routing style, and existing payment/order modules.
2. Select integration mode:
   - Frontend/browser checkout: JavaScript SDK + Public Key Mode.
   - PHP backend: PHP SDK + API Key Mode.
   - Mixed app: backend creates/verifies business records, frontend opens checkout.
3. Read only the relevant reference:
   - PHP backend or Laravel/WordPress/custom PHP: `references/php-sdk.md`
   - Browser/React/Next.js/Vite/static site: `references/js-sdk.md`
   - Webhook endpoint or payment confirmation: `references/webhook.md`
   - Mode selection and security review: `references/integration-modes.md`
4. Install the SDK with the project's package manager.
5. Add environment variable examples:
   - `PONPONPAY_API_KEY` for server-side SDK usage.
   - `PONPONPAY_PUBLIC_KEY` for browser Public Key Mode.
   - `PONPONPAY_API_URL=https://api.ponponpay.com` when the project uses configurable API origins.
6. Implement the smallest useful flow:
   - Create payment order.
   - Return or open `payment_url`.
   - Add webhook verification when backend code exists.
   - Add order status query/polling only if the app needs frontend confirmation.
7. Run available format, typecheck, test, or build commands.
8. Summarize files changed, required env vars, and the manual test path.

## Integration Patterns

### Server-side PHP

Use `composer require ponponpay/php-sdk`, initialize `PonponPay\PonponPay` with `PONPONPAY_API_KEY`, create orders on the server, and redirect users to `paymentUrl`.

### Browser JavaScript

Use `@ponponpay/sdk/browser`, initialize `PonponPayClient` with `PONPONPAY_PUBLIC_KEY`, create orders from the browser, and redirect users to `paymentUrl`. Do not use API Key Mode in browser code.

### Mixed Applications

For production commerce flows, prefer:

- Backend stores the local business order before payment.
- Browser opens PonponPay checkout.
- Webhook verifies the payment and updates the business order.
- Redirect/success page only displays a pending or confirmed state, not the source of truth.

## Done Criteria

- SDK is installed or documented if the user asked not to install.
- Secrets are loaded from environment variables.
- No API Key appears in client bundles.
- Checkout flow creates or opens a PonponPay payment URL.
- Webhook verification is implemented for backend integrations.
- `.env.example` and a short usage note are updated.
- Verification command output is reported to the user.