Skip to main content
Customize the PayNext SDK to align with your brand identity and optimize checkout completion. The SDK provides two customization layers:
LayerWhat you control
VisualStyling, colors, typography, text content, translations
FunctionalPayment methods, validation rules, callbacks, form logic

​
Visual Customization

Control the appearance and text content of the checkout form to match your brand identity.

​
Style the Form

Style elements to integrate seamlessly with your website design:
  • CSS-in-JS styling: Apply React CSS properties directly to components
  • CSS class names: Use custom classes for advanced styling and responsive design
  • Component-specific controls: Separate styling for inputs, buttons, and wallet options

​
Customize Text & Translations

Adapt text content and support multiple languages:
  • Custom labels and messages: Override default text
  • 30+ built-in languages: Automatic browser detection with manual override
  • RTL support: Layout adjusts for right-to-left languages
  • Partial overrides: Change specific text while keeping defaults
Use font sizes of at least 16px on mobile to prevent zoom and ensure sufficient color contrast for accessibility.

​
Functional Configuration

Define how the checkout processes payments and integrates with your app.

​
Manage Payment Methods

Control which options are available and how they’re displayed:
  • Card network filtering: Accept specific card types
  • Layout modes: default (all options) or compact (wallets prioritized)
  • Environment management: Switch between sandbox and production

​
Prefetch the CDN Bundle

The PayNext SDK uses a CDN-based architecture with a small initial JavaScript bundle. The SDK loads dynamically from the PayNext CDN when you mount the checkout form, minimizing your application’s initial bundle size. Preload optimization: Use PayNextSDK.preload() to prefetch the SDK bundle before mounting the checkout form. This reduces the first render time when you can anticipate user navigation (e.g., on pricing pages, when hovering over subscribe buttons, or during checkout page navigation). 
if (typeof window !== 'undefined') {
  PayNextSDK.preload('production').catch(console.error)
}
Preloading is optional but recommended when you can anticipate checkout usage. Always guard the call with a browser check (typeof window !== 'undefined') to keep SSR harmless.
Coordinate post-load work: Use the onCheckoutLoaded callback with the LoadedResult type to detect when the checkout form finishes loading. Once success is true, hide skeletons or trigger follow-up requests; if success is false, surface the embedded CheckoutError. 
import { PayNextCheckout, type LoadedResult } from '@paynext/sdk'

const checkout = new PayNextCheckout()
await checkout.mount('checkout-container', {
  // ... other config
  onCheckoutLoaded: (result: LoadedResult) => {
    if (!result.success) {
      console.error('Checkout failed to load:', result.error)
      return
    }

    // Checkout form is ready—hide loading skeletons or kick off follow-up work
    console.info('Checkout ready')
  },
})

​
Handle Integration Patterns

Respond to events and integrate with your workflow:
  • Success and error callbacks: Custom logic for completion and failure
  • Initial load callback: Run onboarding UI once onCheckoutLoaded signals the checkout is ready (or display a retry on failure)
  • Environment-specific config: Adapt per environment (dev, staging, prod)
Appearance and behavior layers can be applied independently or combined. Start with defaults, then add only what your use case needs.
Digital wallet availability (Apple Pay, Google Pay, PayPal, Venmo, Cash App Pay) depends on both your dashboard configuration and the user’s device/browser capabilities.