PayNext SDK

TypeScript SDK for integrating PayNext payment processing with full type safety and multiple payment methods support.

Installation

npm install @paynext/sdk

Quick Start

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

const checkout = new PayNextCheckout()

await checkout.mount('checkout-form', {
  clientToken: '<you-client-token>',
  environment: 'sandbox',
  apiVersion: '1.0.0',
  onCheckoutLoaded: (result) => {
    // Handle checkout loaded state
    if (result.success) {
      console.info('Checkout loaded successfully')
    } else {
      console.error('Checkout loading failed:', result.error)
    }
  },
  onCheckoutAttempt: (result: AttemptResult) => {
    // Handle payment attempt
    console.info('Payment attempt:', result)
  },
  onCheckoutComplete: (result: PaymentResult) => {
    // Handle successful payment
    console.info('Payment successful!', result)
  },
  onCheckoutFail: (error: CheckoutError) => {
    // Handle payment failure
    console.error('Payment failed:', error)
  }
})

React Example

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

// interface
interface IProps {
  clientToken: string
}

// component
export const CheckoutComponent: FC<Readonly<IProps>> = (props) => {
  const { clientToken } = props
  
  const componentId = 'paynext-checkout'

  useEffect(() => {
    const checkout = new PayNextCheckout()
    
    checkout.mount(componentId, {
      clientToken,
      environment: 'sandbox',
      apiVersion: '1.0.0',
      onCheckoutLoaded: (result) => {
        // Handle checkout loaded state
        if (result.success) {
          console.info('Checkout loaded successfully')
        } else {
          console.error('Checkout loading failed:', result.error)
        }
      },
      onCheckoutAttempt: (result: AttemptResult) => {
        // Handle payment attempt
        console.info('Payment attempt:', result)
      },
      onCheckoutComplete: (result: PaymentResult) => {
        // Handle successful payment
        console.info('Payment completed:', result)
      },
      onCheckoutFail: (error: CheckoutError) => {
        // Handle payment failure
        console.error('Payment failed:', error)
      }
    })

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

  // return
  return <div id={componentId} />
}

Configuration

interface PayNextConfig {
  clientToken: string
  apiVersion: string
  environment: 'sandbox' | 'production'
  variant?: 'default' | 'compact'
  theme?: 'light' | 'dark' | 'system'
  locale?: Locale
  translate?: CheckoutTranslate
  errorMessageText?: string
  returnUrl?: string
  styles?: StylesConfig
  paymentsEnabled?: boolean
  onCheckoutLoaded?: (result: LoadedResult) => void
  beforeCheckoutAttempt?: (result: AttemptResult) => boolean | Promise<boolean>
  onCheckoutAttempt?: (result: AttemptResult) => void
  onCheckoutComplete?: (result: PaymentResult) => void
  onCheckoutFail?: (error: CheckoutError) => void
  onCheckoutBlocked?: (result: AttemptResult) => void // fires on a tap while payments are disabled
}

interface LoadedResult {
  success: boolean
  error?: CheckoutError
}

interface AttemptResult {
  paymentMethod: PaymentMethod
  cardType: string
}

Gate a Payment with beforeCheckoutAttempt

beforeCheckoutAttempt runs before each payment attempt is sent and decides whether it should proceed. It receives the same AttemptResult as onCheckoutAttempt and may be synchronous or return a Promise.

• Return true (or undefined) — the payment proceeds.
• Return false — the attempt is blocked; the SDK surfaces it as a failure via onCheckoutFail.
• Throw / reject — the attempt is treated as a failure and reported through onCheckoutFail.

Use it for last-mile checks such as confirming an order, validating your own state, or asking the user to confirm.

const checkout = new PayNextCheckout()

await checkout.mount('checkout-container', {
  ...config,
  beforeCheckoutAttempt: async (attempt) => {
    // e.g. confirm the order on your backend before charging
    const ok = await confirmOrder(attempt)
    return ok
  }
})

Add a Submit Button Icon

Provide inline SVG markup via styles.SubmitButton.iconSvg to render an icon to the left of the "Pay with card" button label. The SDK hides the icon and shows a spinner while a payment request is in flight, then restores the icon once processing finishes. A 24x24px viewBox keeps the layout balanced.

const checkout = new PayNextCheckout()

await checkout.mount('checkout-container', {
  ...config,
  styles: {
    SubmitButton: {
      iconSvg: `<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none">
        <path d="M6 12L10 16L18 8" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" />
      </svg>`
    }
  }
})

Customize the Back Button

Pass styles.BackButton to adjust the container that wraps the default arrow icon. Both className and styles map directly onto that wrapper <div>, letting you add global CSS hooks or inline overrides without replacing the built-in markup.

const checkout = new PayNextCheckout()

await checkout.mount('checkout-container', {
  ...config,
  styles: {
    BackButton: {
      className: 'my-back-button',
      styles: {
        color: '#111827'
      }
    }
  }
})

Gate Payments Behind Your Own Consent Checkbox

Use paymentsEnabled when payment must be blocked until an external condition is met — for example, the customer ticking your own terms/consent checkbox that lives outside the SDK.

When paymentsEnabled is false:

• Tapping any payment button (Google Pay, PayPal, Apple Pay, etc.) does not start a payment and does not open any provider sheet/popup.
• The card and Pix forms can still expand, but submitting them is blocked.
• Each blocked interaction fires onCheckoutBlocked with the same { paymentMethod, cardType } payload as onCheckoutAttempt, so you can highlight your checkbox.
• Button appearance is unchanged — there is no visual disabled state.

paymentsEnabled defaults to true, so existing integrations are unaffected. Toggle the state at runtime — without re-mounting — with checkout.setPaymentsEnabled(enabled).

const checkout = new PayNextCheckout()

await checkout.mount('checkout-container', {
  ...config,
  // Start blocked until the customer accepts your terms.
  paymentsEnabled: termsAccepted,
  onCheckoutBlocked: ({ paymentMethod }) => {
    // The user tried to pay before accepting — draw attention to your checkbox.
    highlightTermsCheckbox()
    console.info('Payment blocked, terms not accepted:', paymentMethod)
  },
})

// Later, when the customer toggles your checkbox — no re-mount required:
termsCheckbox.addEventListener('change', (e) => {
  checkout.setPaymentsEnabled((e.target as HTMLInputElement).checked)
})

Supported Languages

English, German, French, Spanish, Italian, Portuguese, Dutch, Polish, Czech, Slovak, Hungarian, Romanian, Bulgarian, Croatian, Slovenian, Estonian, Latvian, Lithuanian, Finnish, Swedish, Danish, Norwegian, Russian, Ukrainian, Arabic, Chinese, Japanese, Korean, Thai, Vietnamese, Indonesian, Malay, Filipino, Hindi, Turkish, Greek, Maltese.

TypeScript Support

Full TypeScript support with comprehensive type definitions for all interfaces, payment methods, and configuration options.

Browser Support

The SDK supports recent versions of all major browsers:

• Chrome (v90+)
• Safari (v14+)
• Firefox (v88+)
• Edge (v90+)
• Android WebView / WKWebView (for in-app flows)

Security

PCI DSS compliant with end-to-end encryption. No sensitive payment data is stored locally.