# StartButton Payment Gateway Implementation Guide

This guide shows the recommended frontend-to-backend integration flow.

## 1. Configure the Provider

```tsx
import { StartPayProvider } from "startbutton-payment-gateway";

export const PaymentRoot = ({ children }: { children: React.ReactNode }) => (
  <StartPayProvider
    config={{
      publicKey: "pk_live_xxxxx",
      environment: "production",
      apiBaseUrl: "https://api.yourdomain.com/payments",
      mode: "popup",
      timeout: 30000
    }}
  >
    {children}
  </StartPayProvider>
);
```

## 2. Add the Button

```tsx
import { StartPayButton } from "startbutton-payment-gateway";

export const CheckoutButton = () => (
  <StartPayButton
    amount={1500}
    currency="INR"
    orderId="ORDER_1001"
    customer={{
      name: "Customer Name",
      email: "customer@example.com",
      phone: "9999999999"
    }}
    metadata={{
      cartId: "CART_1001",
      source: "website"
    }}
    onPaymentAuthorized={(response) => {
      console.log("Payment authorized", response.transactionId);
    }}
    onPaymentException={(response) => {
      console.error("Payment exception", response.message);
    }}
  >
    Start Payment
  </StartPayButton>
);
```

## 3. Backend Endpoints Expected by the SDK

Your backend should expose endpoints that create sessions, verify payments, read status, and cancel payments. The exact route names can be mapped inside your backend or adapter layer.

Recommended responsibilities:

- Create payment session with your gateway using secret credentials.
- Return only safe browser data such as session ID, client token, redirect URL, or checkout URL.
- Verify final payment status server-side before fulfilling an order.
- Validate webhook signatures.
- Return normalized status fields where possible.

## 4. Production Checklist

- Use `environment: "production"`.
- Keep secret keys on backend only.
- Use HTTPS for frontend and backend.
- Configure CORS for trusted origins only.
- Store order state server-side.
- Reconcile webhook status with browser-side status.
- Treat browser status as provisional until backend verification completes.

## 5. Local Demo

Run Storybook:

```bash
npm run storybook
```

Then open the Storybook URL shown in your terminal. The included stories are safe documentation examples and do not call a real gateway unless you enable `autoStart` and point `apiBaseUrl` to your backend.