Checkout

Checkout renders the payment step of a checkout your backend created: Stripe’s form for a client secret, or a pay button for a checkout result. When to use

The step after CheckoutButton or PricingTable returns a Stripe client secret.
A payment page that resumes a checkout your backend already created.
A pay button for a Razorpay, hosted or processing checkout, with or without BillingProvider.

Checkout does not need BillingProvider.

Checkout pay button for a checkout result, labelled Pay $29.00, light theme

The screenshots show the pay button of a checkout result. Stripe’s own form takes its look from Stripe and is not shown.

Importing Checkout

import {
  Checkout,
  useCheckout,
  type CheckoutResult,
} from '@nozle-js/react'

Rendering Checkout

Pass a Stripe client secret and your Stripe publishable key:

components/pay-step.tsx

export function PayStep({ clientSecret }: { clientSecret: string }) {
  return (
    <Checkout
      clientSecret={clientSecret}
      publishableKey="pk_live_stripe..."
      returnUrl="https://app.example.com/settings/billing"
      onSuccess={(paymentIntentId) => console.log('paid', paymentIntentId)}
      onError={(error) => console.error(error.message)}
    />
  )
}

A cs_ Checkout Session secret, which Nozle returns for plan and invoice checkout, mounts Stripe Embedded Checkout. Any other Stripe secret mounts Payment Element, themed from your appearance, with a loading placeholder and its own submit button.

Stripe webhooks decide whether the subscription is active. onSuccess, onComplete and the return page are interface signals; reload billing status before you show success.

Data

Checkout takes either a Stripe client secret or a checkout result in the CheckoutResult shape that createCheckout returns:

const result: CheckoutResult = {
  type: 'razorpay',
  checkout_id: 'chk_123',
  key_id: 'rzp_live_...',
  order_id: 'order_123',
  amount_cents: 2900,
  currency: 'INR',
}

export function ResumePayment() {
  return <Checkout checkout={result} submitLabel="Pay ₹29.00" />
}

See checkout result types.

Live data

The client secret comes from onStripeClientSecret of CheckoutButton, PricingTable or UpgradeButton, or from fetchClientSecret of useCheckoutSession. Your Stripe publishable key is your own; Nozle does not return it.

import { useState } from 'react'
import { CheckoutButton } from '@nozle-js/react'

export function BuyPro() {
  const [clientSecret, setClientSecret] = useState<string | null>(null)
  if (clientSecret) return <Checkout clientSecret={clientSecret} publishableKey="pk_live_stripe..." />
  return <CheckoutButton planCode="pro" onStripeClientSecret={setClientSecret} />
}

A stripe result passed as checkout is mounted with Stripe only when it carries a client secret and publishable_key. Nozle does not return publishable_key, so pass a Stripe client secret with clientSecret and publishableKey instead; a stripe result without them shows “Payment setup is incomplete. Contact support to continue.”

Examples

Pay button for a checkout result

With checkout, the component renders a pay button that handles Razorpay, hosted, processing, completed and scheduled results. It reads verifyCheckout and getCheckoutStatus from its props first (React 0.10.0 and later), then from BillingProvider.

import type { CheckoutStatus, RazorpayVerification } from '@nozle-js/react'

const post = async (path: string, body: object): Promise<CheckoutStatus> => {
  const response = await fetch(path, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(body) })
  if (!response.ok) throw new Error(`Request failed: ${response.status}`)
  return response.json()
}

export function ResumePayment({ result }: { result: CheckoutResult }) {
  return (
    <Checkout
      checkout={result}
      submitLabel="Pay ₹29.00"
      verifyCheckout={(checkoutId: string, verification: RazorpayVerification) =>
        post('/api/billing/checkout/verify', { checkoutId, ...verification })
      }
      getCheckoutStatus={(checkoutId: string) => post('/api/billing/checkout/status', { checkoutId })}
      onComplete={() => console.log('done')}
      onDismiss={() => console.log('closed')}
    />
  )
}

Your own pay button

To place your own pay button in the Payment Element form, pass it as children and call useCheckout() in it. children replaces the built-in submit button.

function PayButton() {
  const { confirmPayment, isProcessing, error } = useCheckout()
  return (
    <>
      <button type="button" onClick={() => void confirmPayment()} disabled={isProcessing}>
        {isProcessing ? 'Paying…' : 'Pay now'}
      </button>
      {error && <p role="alert">{error.message}</p>}
    </>
  )
}

export function CustomPay({ clientSecret }: { clientSecret: string }) {
  return (
    <Checkout clientSecret={clientSecret} publishableKey="pk_live_stripe...">
      <PayButton />
    </Checkout>
  )
}

API reference

Checkout takes one of two sets of props.

With a Stripe client secret

string

required

The Stripe client secret. A cs_ Checkout Session secret mounts Embedded Checkout; any other secret mounts Payment Element.

string

required

Your Stripe publishable key.

string

Stripe Connect account ID passed to Stripe.

string

Where Stripe returns the customer after a payment that needs a redirect (Payment Element). Defaults to the current URL.

string

default:"Pay now"

Text of the Payment Element submit button. It reads “Processing…” while the payment is confirmed.

(paymentIntentId: string) => void

Payment Element only. Fires when the PaymentIntent succeeds without a redirect and receives its ID.

() => void

Embedded Checkout only. Fires when the session completes without a redirect. It does not fire when the session redirects to its return URL, which is how Nozle creates sessions.

(error: Error) => void

Fires when the payment fails and receives Stripe’s error, or “Payment could not be confirmed. Check its status before retrying.” when confirming throws. The message also shows under the form.

() => void

Payment Element only. Fires when the form can be used; a loading placeholder shows until then.

ReactNode

Payment Element only. Replaces the submit button. Call useCheckout() inside it. Defaults to a submit button.

string

Class name on the root element.

CSSProperties

Inline styles on the root element.

Appearance

Theme for the wrapper, also mapped onto Payment Element: primary, background, text and danger colours, corner radius and font. A dark card colour picks Stripe’s night theme. Embedded Checkout uses the branding of your Stripe account. Defaults to the provider’s.

With a checkout result

CheckoutResult

required

A result from createCheckout or from a checkout status call.

string

default:"Pay now"

Text of the pay button. It reads “Processing…” while it runs.

string

Passed on to Stripe when the result is mounted with Stripe. Defaults to the current URL.

(checkoutId, verification) => Promise<CheckoutStatus>

Checks a Razorpay payment on your backend. Required for Razorpay. Defaults to the provider’s.

(checkoutId) => Promise<CheckoutStatus>

Reads the checkout status on your backend, polled up to 30 times, one second apart. Required for processing results. Defaults to the provider’s.

(paymentId: string) => void

Fires when a Razorpay payment is captured and fulfilled and receives the payment ID; onComplete fires after it.

() => void

Fires when the checkout completes, including completed and scheduled results.

(status: CheckoutStatus) => void

Fires while payment confirmation is pending and receives the status.

() => void

Fires when the customer closes Razorpay without paying.

(error: Error) => void

Fires when the payment fails and receives the error. The message also shows under the button.

string

Class name on the root element.

Appearance

Theme, variables and element overrides. Defaults to the provider’s. See Appearance.

`useCheckout`

Call useCheckout() only inside children of the Payment Element form; it throws outside Checkout. It is not useCheckoutSession, which creates a checkout.

() => Promise<void>

Confirms the payment.

boolean

true while the payment is confirmed.

Error | null

The last payment error.

States

State	What shows
Payment Element loading	A loading placeholder until the form can be used.
Confirming the payment	”Processing…” on the submit button, or “Processing…” on the pay button.
Waiting for payment confirmation	”Payment is processing. Confirmation may take a little while.”
Payment failed	The error message under the form or button.
`stripe` result without client secret and `publishable_key`	”Payment setup is incomplete. Contact support to continue.”

Checkout shows Powered by Nozle below the form, unless it is inside another component that already shows it.

Appearance

Element keys

checkout (root), checkout__submit (the submit or pay button), checkout__error.Style them with appearance.elements. See Elements.

CheckoutButton

Starts checkout and returns the client secret.

PlanChangeControl

Renders Checkout for a paid upgrade.

Stripe

Connect Stripe to Nozle.

Razorpay

Connect Razorpay to Nozle.

Setup

Components

Billing

Entitlements

Importing Checkout

Rendering Checkout

Data

Live data

Examples

Pay button for a checkout result

Your own pay button

API reference

With a Stripe client secret

With a checkout result

`useCheckout`

States

Appearance

CheckoutButton

PlanChangeControl

Stripe

Razorpay

​Importing Checkout

​Rendering Checkout

​Data

​Live data

​Examples

​Pay button for a checkout result

​Your own pay button

​API reference

​With a Stripe client secret

​With a checkout result

​useCheckout

​States

​Appearance

​Related

CheckoutButton

PlanChangeControl

Stripe

Razorpay

Importing Checkout

Rendering Checkout

Data

Live data

Examples

Pay button for a checkout result

Your own pay button

API reference

With a Stripe client secret

With a checkout result

`useCheckout`

States

Appearance

Related