Skip to main content
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-sideCreate a session using the PayNext API. Pass the session id to your frontend.
Client-sideMount the SDK checkout using the session id.

​
Integration Steps

1

Create Session

Call the PayNext API from your server. See the API Reference for details.POST /client-session
Example Request
{
  "customer": {
    "email": "[email protected]",
    "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.
2

Install SDK

npm install @paynext/sdk
3

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

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).
5

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
6

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

Go Live

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