Quickstart

PayNext SDK automatically supports all payment methods and 3D Secure authentication configured in your dashboard, including cards, Apple Pay, Google Pay, PayPal, and more.

Prerequisites

Create a one-time or subscription plan in Dashboard → Plans
Enable desired payment methods in Dashboard → Checkout
Configure workflows for each enabled payment method in Dashboard → Workflows
PayNext API Key: Available in Dashboard → Developers → API Keys

Never expose your API key in client-side code. Always create client sessions on your server.

How It Works


Server-side	Create a session using the PayNext API. Pass the session `id` to your frontend.
Client-side	Mount the SDK checkout using the session `id`.

Integration Steps

Create Session

Call the PayNext API from your server. See the API Reference for details.POST /client-session

Example Request

{
  "customer": {
    "email": "jane.doe@example.com",
    "external_id": "cust_123",
    "address": { "country": "US" }
  },
  "plan": {
    "id": "plan_7a8b9c0d-1e2f-3a4b-5c6d-7e8f9a0b1c2d"
  }
}

Example Response

{
  "id": "cs_d3b07384-d9a5-4d16-a5b1-3fa3d9b0b123",
  "expiry_date": "2025-08-12T16:14:08Z",
  ...
}

Use the id from the response as your clientToken in the frontend.

Note the expiry_date in the response — sessions expire after this time. If your session expires, create a new one before mounting checkout. For more details, see Handle Expired Sessions.

Install SDK

npm install @paynext/sdk

yarn add @paynext/sdk

pnpm add @paynext/sdk

Preload SDK (Optional)

The SDK uses a CDN-based architecture with a small initial bundle. You can optionally preload the SDK when you anticipate checkout usage (e.g., on pricing pages):

import { PayNextSDK } from '@paynext/sdk'

useEffect(() => {
  if (typeof window !== 'undefined') {
    PayNextSDK.preload('production').catch(console.error)
  }
}, [])

Preloading is recommended as this will speed up how fast payment buttons will load. Without it, the SDK loads on-demand when you call mount.

Configure Return URL

Required for redirect-based payment methods (Cash App, Venmo, etc.). Without it, customers cannot complete checkout.

Point to a page where the checkout is rendered
Optionally, use a URL query parameter (e.g., ?scrollTo=paynext-checkout) to scroll users back to checkout if it’s not at the top of the page

returnUrl: 'https://your-site.com/checkout?scrollTo=paynext-checkout'

Avoid using hash fragments (e.g., #paynext-checkout) in your returnUrl — they are not supported by all alternative payment methods (APM). Use query parameters instead (e.g., ?scrollTo=paynext-checkout).

Mount Checkout

Initialize the SDK with your clientToken and mount the checkout form.

'use client'

import { useEffect, useState } from 'react'
import {
  PayNextCheckout,
  type PaymentResult,
  type AttemptResult,
  type LoadedResult,
  type CheckoutError,
} from '@paynext/sdk'
import '@paynext/sdk/styles'

const CheckoutForm: React.FC = () => {
  const [clientToken, setClientToken] = useState('')

  useEffect(() => {
    let checkout: PayNextCheckout | undefined

    const mountCheckout = async (token: string) => {
      if (!token) return

      checkout = new PayNextCheckout()

      await checkout.mount('paynext-checkout', {
        clientToken: token, // The id from the client session response
        environment: 'sandbox', // 'sandbox' or 'production'
        apiVersion: '1.0.0', // PayNext API version
        returnUrl: 'https://your-site.com/checkout?scrollTo=paynext-checkout', // Your checkout page where user returns after redirect
        locale: 'en',
        onCheckoutLoaded: (result: LoadedResult) => {
          if (!result.success) {
            console.error('Checkout loading failed:', result.error?.status_reason?.message)
            return
          }
          console.info('Checkout loaded successfully')
        },
        onCheckoutAttempt: ({ paymentMethod, cardType }: AttemptResult) => {
          console.info('Payment attempt:', paymentMethod, cardType || '')
        },
        onCheckoutComplete: (result: PaymentResult) => {
          console.log('Payment completed', result)
          window.location.href = '/payment-success'
        },
        onCheckoutFail: (error: CheckoutError) => {
          console.error('Payment failed:', error.status, error.status_reason?.message)
        },
      })
    }

    if (!clientToken) {
      fetch('/api/client-session', { method: 'POST', body: JSON.stringify(payload) })
        .then((r) => r.json())
        .then((data) => setClientToken(data.id))
        .catch(console.error)
    } else {
      mountCheckout(clientToken)
    }

    return () => {
      checkout?.unmount()
    }
  }, [clientToken])

  return <div id='paynext-checkout' />
}

export default CheckoutForm

import {
  PayNextCheckout,
  type PaymentResult,
  type AttemptResult,
  type LoadedResult,
  type CheckoutError,
} from '@paynext/sdk'
import '@paynext/sdk/styles'

async function init() {
  const res = await fetch('/api/client-session', { method: 'POST', body: JSON.stringify(payload) })
  const { id: clientToken } = await res.json()

  const checkout = new PayNextCheckout()

  await checkout.mount('paynext-checkout', {
    clientToken, // The id from the client session response
    environment: 'sandbox', // 'sandbox' or 'production'
    apiVersion: '1.0.0', // PayNext API version
    returnUrl: 'https://your-site.com/checkout?scrollTo=paynext-checkout', // Your checkout page where user returns after redirect
    locale: 'en',
    onCheckoutLoaded: (result: LoadedResult) => {
      if (!result.success) {
        console.error('Checkout loading failed:', result.error?.status_reason?.message)
        return
      }
      console.info('Checkout loaded successfully')
    },
    onCheckoutAttempt: ({ paymentMethod, cardType }: AttemptResult) => {
      console.info('Payment attempt', paymentMethod, cardType || '')
    },
    onCheckoutComplete: (result: PaymentResult) => {
      console.info('Success', result)
    },
    onCheckoutFail: (error: CheckoutError) => {
      console.error('Payment failed:', error.status, error.status_reason?.message)
    },
  })
}

init()

Test

Use the sandbox environment and test payment details available for your payment method and processor to validate your setup.

Track test payments in Dashboard → Payments. For Apple Pay and Google Pay, ensure your browser and device meet eligibility requirements.

Go Live

Change environment to 'production' in your SDK config
Use production API keys on your backend
Test with real payment methods before launch
Set up webhooks for payment confirmations

onCheckoutComplete is a client-side UX signal, not a settlement confirmation — and it is not guaranteed to run. It fires in the customer’s browser, so a closed or backgrounded tab or a lost connection can prevent it, on any payment method (seen on PayPal and Apple Pay); for asynchronous methods such as Pix the payment can also still be settling when it fires. Grant access and fulfill orders from payment webhooks — the source of truth for the final payment status.

Getting Started

Use Cases

Customization

Constants

Prerequisites

How It Works

Integration Steps

​Prerequisites

​How It Works

​Integration Steps

Prerequisites

How It Works

Integration Steps