# StartButton Payment Gateway

[![npm version](https://img.shields.io/npm/v/startbutton-payment-gateway.svg)](https://www.npmjs.com/package/startbutton-payment-gateway)
[![TypeScript](https://img.shields.io/badge/TypeScript-ready-3178c6.svg)](https://www.typescriptlang.org/)
[![React](https://img.shields.io/badge/React-18%20%7C%2019-61dafb.svg)](https://react.dev/)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
[![Storybook](https://img.shields.io/badge/Storybook-ready-ff4785.svg)](https://storybook.js.org/)

**StartButton Payment Gateway** is a React + TypeScript SDK for building a polished, customizable, backend-first payment button experience. It gives developers a ready payment button, hook API, normalized JSON responses, typed callbacks, and flexible checkout modes without bundling any third-party gateway SDK into your runtime package.

Built by **Pradeep Kumar Sheoran (Developer)** at **BSG Technologies**.

**Official Website:** [https://bsgtechnologies.com](https://bsgtechnologies.com)  
Visit here to meet, learn, contribute, and discuss new topics with us.

**Contact / WhatsApp:** +91-8595147850

## Why Developers Choose It

- TypeScript-first API with exported response, callback, config, and payment input types.
- Advanced callback names for better product feel: `onPaymentAuthorized`, `onPaymentDeclined`, `onPaymentPendingReview`, `onPaymentAborted`, `onPaymentException`, and `onPaymentSettled`.
- Backward-compatible callbacks: `onSuccess`, `onFailure`, `onPending`, `onCancel`, and `onError` still work.
- Customizable button labels, styles, native button props, render-prop UI, and manual launch control.
- React 18 and React 19 compatible peer dependency range.
- Backend-first security flow: secret keys stay on your server.
- Normalized JSON responses across success, failed, pending, cancelled, and error states.
- Popup, redirect, iframe, and custom gateway adapter architecture.
- Storybook-ready component documentation and isolated development workflow.
- No bundled third-party payment gateway library in the runtime SDK.

## Hashtags

`#ReactPaymentGateway` `#TypeScriptSDK` `#StartPay` `#PaymentButton` `#SecureCheckout` `#BSGTechnologies` `#IndiaPayments` `#UPI` `#ReactSDK`

## Installation

```bash
npm install startbutton-payment-gateway
```

React is a peer dependency and is not bundled.

## Quickstart

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

export const App = () => (
  <StartPayProvider
    config={{
      publicKey: "pk_test_xxxxx",
      environment: "sandbox",
      apiBaseUrl: "https://api.yourdomain.com",
      mode: "popup"
    }}
  >
    <StartPayButton
      amount={1500}
      currency="INR"
      orderId="ORDER_1001"
      customer={{
        name: "Pradeep Kumar",
        email: "customer@example.com",
        phone: "9999999999"
      }}
      loadingText="Launching secure checkout..."
      successText="Payment Authorized"
      failureText="Payment Declined"
      className="startpay-button"
      onPaymentAuthorized={(response) => console.log("Authorized", response)}
      onPaymentDeclined={(response) => console.log("Declined", response)}
      onPaymentException={(response) => console.log("Exception", response)}
      onPaymentSettled={(response) => console.log("Final response", response)}
    >
      Start Payment
    </StartPayButton>
  </StartPayProvider>
);
```

## Advanced Button API

```tsx
<StartPayButton
  amount={2499}
  currency="INR"
  orderId="ORDER_PREMIUM_1002"
  autoStart={false}
  onClick={async (_event, controls) => {
    console.log("Current status", controls.lastStatus);
    await controls.launchPaymentFlow();
  }}
  onPaymentPendingReview={(response) => console.log("Pending", response)}
  onPaymentAborted={(response) => console.log("Cancelled", response)}
>
  Pay Securely
</StartPayButton>
```

Render your own UI when you want full design control:

```tsx
<StartPayButton amount={1500} currency="INR" orderId="ORDER_CUSTOM_1003">
  {({ loading, disabled, lastStatus, launchPaymentFlow }) => (
    <button type="button" disabled={disabled} onClick={launchPaymentFlow}>
      {loading ? "Processing..." : lastStatus ? `Status: ${lastStatus}` : "Pay Now"}
    </button>
  )}
</StartPayButton>
```

## Hook Usage

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

const PayNow = () => {
  const { startPayment, loading } = useStartPay();

  const handlePayment = async () => {
    const response = await startPayment({
      amount: 1500,
      currency: "INR",
      orderId: "ORDER_1001"
    });

    if (response.status === "success") {
      console.log(response.transactionId);
    }
  };

  return (
    <button type="button" disabled={loading} onClick={handlePayment}>
      {loading ? "Processing..." : "Pay Now"}
    </button>
  );
};
```

## Backend Connection Flow

Your frontend SDK should call your own backend. Your backend talks to the actual payment gateway and keeps secret credentials private.

1. React app calls your backend to create a payment session.
2. Backend creates the gateway order/session using secret credentials.
3. Backend returns `paymentSessionId`, `clientToken`, `redirectUrl`, or `checkoutUrl`.
4. SDK opens popup, redirect, iframe, or custom checkout flow.
5. SDK receives browser-side result.
6. React app asks backend to verify the payment.
7. Backend verifies gateway status/signature.
8. SDK returns one normalized response object.

See [docs/IMPLEMENTATION_GUIDE.md](docs/IMPLEMENTATION_GUIDE.md) and [examples/backend.example.ts](examples/backend.example.ts).

## Response Example

```ts
{
  status: "success",
  success: true,
  paymentId: "PAY_123456",
  orderId: "ORDER_1001",
  transactionId: "TXN_987654",
  amount: 1500,
  currency: "INR",
  gateway: "custom",
  message: "Payment completed successfully",
  metadata: {},
  timestamp: "2026-07-01T13:30:00.000Z"
}
```

Full response reference: [docs/RESPONSE_REFERENCE.md](docs/RESPONSE_REFERENCE.md).

## Storybook

Develop and document the component in isolation:

```bash
npm run storybook
```

Build static Storybook docs:

```bash
npm run build:storybook
```

The Storybook story uses `autoStart={false}` for safe local documentation, so opening the demo does not call a real payment endpoint until you wire your backend.

## Live Demo Pattern

This repository includes copy-ready examples:

- [examples/basic.example.tsx](examples/basic.example.tsx)
- [examples/hook.example.tsx](examples/hook.example.tsx)
- [examples/advanced-customization.example.tsx](examples/advanced-customization.example.tsx)
- [examples/backend.example.ts](examples/backend.example.ts)

For a public live demo, deploy your React app and set `apiBaseUrl` to your backend payment API. Keep all secret keys on the backend.

## TypeScript Developer Experience

```ts
import type {
  StartPayButtonCallback,
  StartPayConfig,
  StartPaymentInput,
  StartPayResponse
} from "startbutton-payment-gateway";

const config: StartPayConfig = {
  publicKey: "pk_test_xxxxx",
  environment: "sandbox",
  apiBaseUrl: "https://api.yourdomain.com"
};

const payment: StartPaymentInput = {
  amount: 1500,
  currency: "INR",
  orderId: "ORDER_1001"
};

const onSettled: StartPayButtonCallback = (response: StartPayResponse) => {
  console.log(response.status);
};
```

## Customization Options

- `className`, `style`, `id`, `name`, `aria-*`, and `data-*` native button props.
- `loadingText`, `successText`, and `failureText` labels.
- `autoStart={false}` for manual control.
- Render-prop children for fully custom UI.
- `signal` for abort-aware payment requests.
- `timeout`, `paymentMethods`, `callbackUrl`, `returnUrl`, `customer`, and `metadata`.
- Callback aliases for both practical coding and premium product naming.

## Security Notes

- Never pass a secret key to frontend config.
- Verify payment status on your backend before fulfilling an order.
- Use HTTPS in production.
- Validate webhook signatures on the backend.
- Log normalized responses, but do not store sensitive card or credential data.

## Donation and Support

If this SDK helps your project, you can support development:

**UPI / Mobile:** +91-8595147850

For business discussion, integration help, contribution, or collaboration:

**BSG Technologies:** [https://bsgtechnologies.com](https://bsgtechnologies.com)  
**Developer:** Pradeep Kumar Sheoran  
**Contact / WhatsApp:** +91-8595147850

## Build

```bash
npm run typecheck
npm run build
```

The package builds ESM, CJS, and TypeScript declarations with `sideEffects: false` for tree shaking.

## License

MIT. See [LICENSE](LICENSE).