Customize Checkout Behavior

​

When and Why to Configure Behavior

​

Configure via PayNextConfig

​

Supported Card Networks

​

Restrict Card Networks per Payment Method

import { PayNextCheckout, PaymentMethod, CardType } from "@paynext/sdk";

const checkout = new PayNextCheckout();

checkout.mount("paynext-checkout", {
  clientToken,
  environment: "production",
  apiVersion: "1.0.0",
  acceptedCardNetworks: {
    [PaymentMethod.CARD]:       [CardType.Visa, CardType.Mastercard],
    [PaymentMethod.APPLE_PAY]:  [CardType.Visa, CardType.AmericanExpress],
    [PaymentMethod.GOOGLE_PAY]: [], // empty -> falls back to the dashboard default
  },
});

• A non-empty list overrides the dashboard configuration for that method — it can both narrow and widen the accepted set, bounded to what the method technically supports. Networks the method doesn’t support are dropped (for example, CardType.AmericanExpress on the CARD method).
• An empty array [], a missing key, or a list of only unsupported networks falls back to the dashboard default. A method is never left with zero networks, and its button is never hidden.
• Keys other than CARD, APPLEPAY, and GPAY are ignored.

​

Advanced Patterns

​

Gate Payments Behind a Consent Checkbox

• Tapping any payment button (Google Pay, PayPal, Apple Pay, etc.) does not start a payment and does not open the provider’s sheet or popup.
• The card and Pix forms can still expand, but submitting them is blocked.
• Every blocked interaction fires onCheckoutBlocked with { paymentMethod, cardType }, so you know which button was tapped and can react (e.g. highlight your checkbox).
• Buttons render identically — there is no visual disabled state.

const checkout = new PayNextCheckout()

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

// When the customer toggles your checkbox, push the new state to the SDK.
// This takes effect immediately, without re-mounting.
termsCheckbox.addEventListener('change', (event) => {
  checkout.setPaymentsEnabled((event.target as HTMLInputElement).checked)
})

​

Update Configuration at Runtime

const checkout = new PayNextCheckout()

await checkout.mount('paynext-checkout', { ...config, locale: 'en', theme: 'light' })

// Later — e.g. the customer switches language or toggles dark mode in your UI.
// Each call applies immediately, without re-mounting, and keeps form state.
checkout.update({ locale: 'es' })
checkout.update({ theme: 'dark' })
checkout.update({ paymentsEnabled: false })

​

Digital Wallet Configuration

​

Payment Method Priority

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

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

​

Understanding Payment Method Availability

​

Layout Variants

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

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

​

Success States and Decline Messages

​

Best Practices

​

Environment Configuration

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

​

Common Pitfalls

• 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