Quick Start

Go from zero to accepting payments in five minutes. This guide walks you through installing PayKit, creating a charge on the server, collecting payment on the client, handling webhooks, and switching providers with a single line change.

1. Install packages

Install the core SDK together with the adapter for your payment provider. The example below uses Stripe, but you can swap it for any supported adapter later.

Terminal

# Core SDK + Stripe provider SDK
npm install @squaredr/paykit stripe

# React bindings (for frontend checkout)
npm install @squaredr/paykit-react

2. Backend: Create a payment intent

On your server, initialise PayKit with the Stripe adapter and create a charge. The returned clientSecret is what the frontend needs to confirm the payment.

server/checkout.ts

import { PayKit } from '@squaredr/paykit'
import { StripeAdapter } from '@squaredr/paykit/stripe'

// Initialise PayKit with the Stripe adapter
const paykit = new PayKit({
  adapter: new StripeAdapter({
    secretKey: process.env.STRIPE_SECRET_KEY!,
  }),
})

// Create a charge (amount is in the smallest currency unit)
const charge = await paykit.charges.create({
  amount: 5000,          // $50.00
  currency: 'usd',
  metadata: {
    orderId: 'order_abc123',
    customer: 'cust_42',
  },
})

// Send the clientSecret to the frontend
console.log(charge.clientSecret)

3. Frontend: Collect payment

Wrap your checkout UI with PayKitProvider and render the pre-built CheckoutForm. The provider handles loading the correct provider SDK behind the scenes.

app/checkout/page.tsx

'use client'

import { useState, useEffect } from 'react'
import { PayKitProvider, CheckoutForm } from '@squaredr/paykit-react'
import { StripeClientAdapter } from '@squaredr/paykit/stripe/client'

const stripeClient = new StripeClientAdapter({
  publishableKey: process.env.NEXT_PUBLIC_STRIPE_PK!,
})

export default function CheckoutPage() {
  const [clientSecret, setClientSecret] = useState<string | null>(null)

  useEffect(() => {
    fetch('/api/checkout', { method: 'POST' })
      .then((res) => res.json())
      .then((data) => setClientSecret(data.clientSecret))
  }, [])

  if (!clientSecret) return <p>Loading...</p>

  return (
    <PayKitProvider adapter={stripeClient} clientSecret={clientSecret}>
      <CheckoutForm
        onSuccess={(result) => {
          console.log('Payment succeeded:', result.id)
        }}
        onError={(err) => {
          console.error('Payment failed:', err.message)
        }}
      />
    </PayKitProvider>
  )
}

4. Handle webhooks

Webhooks let your server react to asynchronous payment events. PayKit normalises every provider's webhook payload into a unified event shape so your handler logic stays the same regardless of provider.

app/api/webhooks/route.ts

import { PayKit } from '@squaredr/paykit'
import { StripeAdapter } from '@squaredr/paykit/stripe'

const paykit = new PayKit({
  adapter: new StripeAdapter({
    secretKey: process.env.STRIPE_SECRET_KEY!,
  }),
})

export async function POST(req: Request) {
  const body = await req.text()
  const signature = req.headers.get('stripe-signature')!
  const secret = process.env.STRIPE_WEBHOOK_SECRET!

  // Verify the signature and parse the event
  const event = paykit.webhooks.construct({
    payload: body,
    signature,
    secret,
  })

  switch (event.type) {
    case 'payment.succeeded':
      console.log('Payment succeeded:', event.data.id)
      // fulfil the order
      break
    case 'payment.failed':
      console.log('Payment failed:', event.data.id)
      // notify the customer
      break
  }

  return new Response('ok', { status: 200 })
}

5. Switch providers

Because every adapter exposes the same interface, switching from Stripe to Razorpay (or any other supported provider) is a one-line change. Your charge creation code, webhook handler, and frontend components stay exactly the same.

server/checkout.ts

// Before — Stripe
// import { StripeAdapter } from '@squaredr/paykit/stripe'

// After — Razorpay
import { RazorpayAdapter } from '@squaredr/paykit/razorpay'

const paykit = new PayKit({
  adapter: new RazorpayAdapter({
    keyId: process.env.RAZORPAY_KEY_ID!,
    keySecret: process.env.RAZORPAY_KEY_SECRET!,
  }),
})

Everything downstream — charges, webhooks, the React checkout — works without modification.

Next Steps

Stripe Guide — deep dive into Stripe-specific configuration and features.
Razorpay Guide — set up Razorpay for INR payments and UPI.
Webhooks Guide — advanced webhook patterns, retry handling, and event mapping.

← PreviousInstallation Next →Architecture