Customize Checkout Behavior

When and Why to Configure Behavior

Configure checkout form behavior to optimize for your specific business requirements and user demographics. Strategic configuration helps reduce payment failures while improving user experience.

Card Network Filtering

Optimize payment acceptance by controlling which card brands to support. Reduce processing fees and improve conversion rates by accepting only the most relevant cards for your target markets and business agreements.

Payment Method Priority

Payment method ordering and priority are automatically managed through the PayNext Dashboard. The SDK automatically optimizes for user context and device capabilities.

Callback Integration

Build robust payment workflows with comprehensive event handling. Implement custom business logic, analytics tracking, and user experience flows that respond to payment success, failures, and different payment methods.

Environment Management

Ensure reliable deployments across all environments with proper configuration management. Set up environment-specific validation, error handling, and testing strategies that prevent production issues and maintain security.

Configure via `PayNextConfig`

Configure checkout form behavior through the PayNextConfig interface:

Create the instance with new PayNextCheckout() and pass the element ID as the first parameter and your assembled PayNextConfig as the second parameter into checkout.mount('element-id', { ...config }) as demonstrated in Mount the Checkout. Apply the configuration fragments below before calling mount.

Show Core Configuration Properties

clientToken

string

required

Client session token from your server endpoint. See Create a Client Session for server-side setup guidance.

environment

'sandbox' | 'production'

required

Processing environment. Use sandbox for testing, production for live payments. Review Environment Types for recommended usage.

apiVersion

string

required

PayNext SDK/API version (e.g., "1.0.0").

variant

'default' | 'compact'

Layout variant: default shows all methods, compact prioritizes digital wallets. Compare outcomes in Layout Variants.

locale

string

Language code (e.g., en, es). Defaults to browser language detection. Explore localization strategies in Customize Text & Translations.

errorMessageText

string

Override the localized global error banner that appears when checkout initialization fails. Provide custom copy if you need to match brand tone or include support instructions. See Override the Global Error Banner for implementation details.

returnUrl

string

URL to return users after off-site steps. Use a hash to auto-scroll back to an embedded checkout (e.g., https://your-site.com/checkout/return#paynext-checkout).

onCheckoutLoaded

(result: LoadedResult) => void

Fires once after the checkout UI finishes loading. Use it to hide skeletons, log the LoadedResult.error when success is false, or trigger follow-up requests once the form is ready. See callback orchestration patterns in Integration Patterns.

onCheckoutAttempt

(result: AttemptResult) => void

Fires whenever a user starts a payment attempt (e.g., selecting Apple Pay or Cash App Pay). The callback receives { paymentMethod, cardType }, where paymentMethod can be 'CARD', 'APPLEPAY', 'GPAY', 'PAYPAL', 'VENMO', or 'CASHAPP' (for Stripe only). For card payments, cardType contains the brand string such as \"visa\", \"mastercard\", etc. For digital wallet payments (including Cash App Pay), cardType is an empty string. Useful for analytics or disabling UI while processing. See callback orchestration patterns in Integration Patterns.

onCheckoutComplete

(result: PaymentResult) => void

Callback fired when payment completes successfully. The PaymentResult includes payment details, customer information, and payment method data. Use the server-side webhook payload (or your own payment storage) if you need processor-specific metadata such as Stripe customer/payment method IDs for Cash App Pay. See callback orchestration patterns in Integration Patterns.

onCheckoutFail

(error: CheckoutError) => void

Callback fired when payment fails or encounters an error. See callback orchestration patterns in Integration Patterns. The CheckoutError provides a status ('declined' or 'failed') and a structured status_reason with advice_code, an optional decline_code, and a localized message.

Pair onCheckoutLoaded with a loading spinner or skeleton to ensure the checkout only appears once assets and payment methods are ready. If the callback reports success: false, show a retry CTA and log the included CheckoutError.

Supported Card Networks

Visa

CardType.Visa

Mastercard

CardType.Mastercard

JCB

CardType.JCB

Diners Club

CardType.DinersClub

UnionPay

CardType.UnionPay

Maestro

CardType.Maestro

Advanced Patterns

Digital Wallet Configuration

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.

All digital wallet configurations (merchant names, supported networks, authentication settings) are managed in your PayNext dashboard. No code changes are required when enabling or disabling payment methods.

Payment Method Priority

Set priority directly in the PayNext Dashboard (Checkout → Payment methods). Drag to reorder wallets, toggle them on/off, and add conditions for card visibility. The SDK reads this configuration on every load—no code changes or redeploys required.

How Ordering Works:

The dashboard order becomes the exact order shown in the SDK (top to bottom).
If you never customized the list, PayNext falls back to its default order: digital wallets → PayPal → cards.
When a method is disabled or hidden by conditions, the SDK closes the gap and keeps the remaining order intact.

Automatic Optimization Features (handled by the SDK):

Shows payment methods available to the customer’s device/browser (e.g., hides Apple Pay on Windows)
Applies your dashboard ordering after filtering out unsupported methods
Respects your conditions per processor/country/currency
Automatically hides methods when a processor disconnects or the customer’s device can’t use it.

Reordering the list in the dashboard is the quickest way to run A/B tests on wallet prominence—no SDK updates are necessary.

Understanding Payment Method Availability

The SDK determines payment method availability using multiple factors:

Device Capabilities

Apple Pay: Safari on iOS/macOS with Apple Pay configured
Google Pay: Chrome/Chromium browsers with Google Pay enabled
PayPal: Shown when enabled in your dashboard
Venmo: Shown for US users on desktop browsers (via QR code) and mobile browsers (via deep link or web fallback)
Cash App Pay: Available when Stripe + Cash App Pay are enabled and the customer is in a supported region/device context

Geographic Optimization

North America: Prioritizes Apple Pay, Google Pay, PayPal, Venmo
Europe: Emphasizes Apple Pay, Google Pay, PayPal, SEPA
Asia: Focuses on local payment methods and digital wallets
Global: Falls back to major card networks (Visa, Mastercard)

User Behavior Patterns

Returning users: May see previously used payment methods first
Mobile users: Digital wallets prioritized over card forms
Desktop users: Traditional card forms are more prominent
High-value transactions: May show premium payment options first

Layout Variants

Control how payment methods are initially presented:

Default Layout
Compact Layout

// When mounting (see Getting Started "Mount the Checkout" section):
const checkout = new PayNextCheckout()
await checkout.mount('checkout-container', {
  ...config,
  variant: 'default',
})

Refer to Mount the Checkout for the complete mounting flow.

Use cases:

Desktop-focused experiences
Users are comfortable with traditional forms
When screen space is abundant
Clear overview of all payment options needed

// When mounting (see Getting Started "Mount the Checkout" section):
const checkout = new PayNextCheckout()
await checkout.mount('checkout-container', {
  ...config,
  variant: 'compact',
})

Refer to Mount the Checkout for the complete mounting flow.

Use cases:

Mobile-first experiences
Digital wallet adoption priority
Cleaner, less cluttered interface
Users prefer quick payment methods

Compact mode can increase digital wallet usage by 15-25% by featuring them prominently.

Success States and Decline Messages

The SDK automatically handles success states and localized decline fallback messaging across all devices and browsers. Success States The SDK automatically displays success confirmations when payments are completed successfully. No additional configuration is required. Decline Messages When a payment is declined, the SDK displays a single localized fallback message regardless of the specific decline reason:

“We are unable to authenticate your payment method. Please choose a different payment method and try again.”

This consistent messaging approach simplifies the user experience while maintaining security by not exposing specific decline details

Best Practices

Environment Configuration

Configure different behavior per environment:

environment-detection.ts

import { PayNextCheckout, type PayNextConfig } from '@paynext/sdk'

export async function mountEnvironmentAwareCheckout(containerId: string) {
  const isProduction = process.env.NODE_ENV === 'production'
  const isDevelopment = process.env.NODE_ENV === 'development'
  
  // Environment-specific configuration
  const config: PayNextConfig = {
    clientToken: isProduction 
      ? process.env.NEXT_PUBLIC_PAYNEXT_PROD_TOKEN!
      : process.env.NEXT_PUBLIC_PAYNEXT_SANDBOX_TOKEN!,
    environment: isProduction ? 'production' : 'sandbox', // 'sandbox' | 'production'  
    variant: isProduction ? 'compact' : 'default',
    /* other options */
  }
  
  const checkout = new PayNextCheckout()
  await checkout.mount(containerId, config)
  return checkout
}

Form Validation and Error Handling

The SDK provides real-time validation for all payment fields:

Card Number Validation

Format validation: Checks card number format in real-time
Card type detection: Automatically detects Visa, Mastercard, etc.
Luhn algorithm: Validates card number using industry standard
Length verification: Ensures correct number of digits

Expiry Date Validation

Format checking: MM/YY format validation
Date logic: Validates month (01-12) and future dates
Expiry detection: Prevents expired card acceptance
Input formatting: Auto-formats as user types

Security Code (CVC) Validation

Length validation: 3 digits for most cards, 4 for Amex
Numeric verification: Ensures only numbers are entered
Real-time feedback: Immediate validation as user types
Card-specific rules: Adapts based on detected card type

Common Pitfalls

Avoid these behavior configuration mistakes:

Overly restrictive card filtering that excludes common payment methods
Missing error handling for network or payment failures
Exposing sensitive data in client-side error messages
Not testing across environments before production deployment
Ignoring mobile-specific considerations for payment method availability

Test all behavior configurations thoroughly in a sandbox environment before deploying to production

Getting Started

Use Cases

Customization

Constants

When and Why to Configure Behavior

Card Network Filtering

Payment Method Priority

Callback Integration

Environment Management

Configure via `PayNextConfig`

Supported Card Networks

Visa

Mastercard

JCB

Diners Club

UnionPay

Maestro

Advanced Patterns

Digital Wallet Configuration

Payment Method Priority

Understanding Payment Method Availability

Layout Variants

Success States and Decline Messages

Best Practices

Environment Configuration

Form Validation and Error Handling

Common Pitfalls

Getting Started

Use Cases

Customization

Constants

​When and Why to Configure Behavior

Card Network Filtering

Payment Method Priority

Callback Integration

Environment Management

​Configure via PayNextConfig

​Supported Card Networks

Visa

Mastercard

JCB

Diners Club

UnionPay

Maestro

​Advanced Patterns

​Digital Wallet Configuration

​Payment Method Priority

​Understanding Payment Method Availability

​Layout Variants

​Success States and Decline Messages

​Best Practices

​Environment Configuration

​Form Validation and Error Handling

​Common Pitfalls

When and Why to Configure Behavior

Configure via `PayNextConfig`

Supported Card Networks

Advanced Patterns

Digital Wallet Configuration

Payment Method Priority

Understanding Payment Method Availability

Layout Variants

Success States and Decline Messages

Best Practices

Environment Configuration

Form Validation and Error Handling

Common Pitfalls