StartButton Payment Gateway

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
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

npm install startbutton-payment-gateway

React is a peer dependency and is not bundled.

Quickstart

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: "[email protected]",
        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

<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:

<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

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 and examples/backend.example.ts.

Response Example

{
  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.

Storybook

Develop and document the component in isolation:

npm run storybook

Build static Storybook docs:

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/hook.example.tsx
• examples/advanced-customization.example.tsx
• 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

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
Developer: Pradeep Kumar Sheoran
Contact / WhatsApp: +91-8595147850

Build

npm run typecheck
npm run build

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

License

MIT. See LICENSE.