Customize Text & Translations - Documentation

When and Why to Customize Text

Customize checkout form text to match your brand voice, provide clearer user guidance, and support international customers. Text customization helps create a cohesive experience that aligns with your existing user interface patterns.

Complete Control

Override labels, buttons, validation messages, and status notifications.

Multi-Language Support

30+ built-in translations with automatic browser language detection.

RTL Language Support

Automatic right-to-left layout adjustment for Arabic and other RTL languages.

Partial Overrides

Change only specific text elements while keeping default translations for others.

Implement Language Detection

The PayNext SDK automatically detects the user’s preferred language from browser settings:

Provide the locale and translate properties on the object you pass into checkout.mount('element-id', { ...config }) after creating the instance with new PayNextCheckout(), as shown in Mount the Checkout. The snippets below focus on those configuration objects.

import { useState } from 'react'
import { type PayNextConfig } from '@paynext/sdk'

const defaultConfig: PayNextConfig = {
  /* other options */
  // locale omitted: automatic detection
}

const spanishConfig: PayNextConfig = {
  ...defaultConfig,
  locale: 'es', // Manual override
}

// Dynamic language switching (React example)
const [currentLocale, setCurrentLocale] = useState(
  navigator.language.split('-')[0]
)

const dynamicConfig: PayNextConfig = {
  ...defaultConfig,
  locale: currentLocale,
}

The SDK reads errorMessageText from the same configuration object you pass into checkout.mount(...). That value flows straight into the checkout state and overrides the localized fallback string shown in the global error banner.

this.core.state.checkout.setState({
  clientToken: config.clientToken,
  environment: config.environment,
  apiVersion: config.apiVersion,
  errorMessageText: config.errorMessageText,
})

The banner itself respects that override when the alert component is created:

if (customErrorMessage) {
  this.message.textContent = customErrorMessage
  this.hasCustomMessage = true
  this.hasConfigMessage = true
} else {
  this.message.textContent = translate.messages().status.error
}

Provide your copy on the config object to replace the default message with brand-specific instructions or support details.

Customize Text (Examples)

Basic Override
Complete Override
Validation Messages

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

const customTranslations: DeepPartial<CheckoutTranslate> = {
  card: {
    required: 'Please fill in every required field.',
    pay: { button: 'Complete purchase' },
    compact: { button: 'Pay with card' }
  },
  status: {
    error: 'Unable to process payment. Please try again.',
    invalidSession: 'Your session expired. Refresh and try again.',
    authenticationFailed: 'Your payment method authentication was unsuccessful. Please try submitting the payment again and complete the authentication process, or use a different payment method.'
  }
}

export async function mountCustomTranslations(
  containerId: string,
  baseConfig: PayNextConfig
) {
  const checkout = new PayNextCheckout()
  await checkout.mount(containerId, {
    ...baseConfig,
    translate: customTranslations,
  })
  return checkout
}

You can pass a partial object. Any missing strings fall back to built-in translations.

import { type CheckoutTranslate } from '@paynext/sdk'

const completeCustomTranslations: CheckoutTranslate = {
  card: {
    required: 'Please complete every field before continuing.',

    // Card number field
    number: {
      label: 'Credit Card Number',
      error: {
        invalid: 'Enter a valid card number.',
        incomplete: 'Your card number is incomplete.',
        unsupported: 'This card type is not accepted.'
      }
    },

    // Expiry date field
    expiry: {
      label: 'Expiration Date',
      placeholder: 'MM/YY',
      error: {
        invalid: 'Enter a valid expiry date.',
        incomplete: 'The expiry date is incomplete.',
        expired: 'This card has expired.',
        tooFarInFuture: 'The expiry date looks too far in the future.'
      }
    },

    // Security code field
    cvc: {
      label: 'Security Code',
      placeholder: 'CVC',
      error: {
        incomplete: 'The security code is incomplete.'
      }
    },

    // Cardholder name field
    name: {
      label: 'Cardholder Name',
      placeholder: 'Full name as shown on card'
    },

    // Payment buttons
    pay: {
      button: 'Complete Payment'
    },
    compact: {
      button: 'Credit or Debit Card'
    }
  },

  // Status messages
  status: {
    error: 'We couldn\'t process your payment. Please check your information and try again.',
    invalidSession: 'Your payment session expired. Refresh to continue.',
    authenticationFailed: 'Your payment method authentication was unsuccessful. Please try submitting the payment again and complete the authentication process, or use a different payment method.'
  },

  // Optional processor error overrides
  errors: {
    doNotHonor: 'Your bank declined the payment.',
    insufficientFunds: 'There are insufficient funds to complete the payment.',
    limitExceeded: 'This payment exceeds the card limit.',
    expiredCard: 'This card has expired.',
    invalidCreditCardNumber: 'Enter a valid card number.',
    processorDeclinedFraudSuspected: 'The transaction was declined for security reasons.',
    cardholderAuthenticationRequired: 'Additional verification is required to complete the payment.',
    offlineIssuerDeclined: 'The issuer was unreachable to approve the transaction.',
    cardReportedAsLostOrStolen: 'This card has been reported lost or stolen.',
    invalidSecurePaymentData: 'Secure payment data was invalid.',
    declined: 'The payment was declined.'
  }
}

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

Refer to Mount the Checkout for the complete mounting flow.

import { type CheckoutTranslate, type DeepPartial } from '@paynext/sdk'

const helpfulValidations: DeepPartial<CheckoutTranslate> = {
  card: {
    number: {
      error: {
        required: 'Please enter your card number',
        invalid: 'This doesn\'t look like a valid card number',
        incomplete: 'Please enter your complete card number',
        unsupported: 'We don\'t accept this card type. Try Visa or Mastercard.'
      }
    },
    expiry: {
      error: {
        required: 'When does your card expire?',
        invalid: 'Please check your card\'s expiry date',
        incomplete: 'Please enter the full expiry date',
        expired: 'This card has expired. Please use a different card.'
      }
    },
    cvc: {
      error: {
        required: 'Please enter your card\'s security code',
        invalid: 'Please check the security code',
        incomplete: 'Please enter the complete security code (usually 3-4 digits)'
      }
    },
    name: {
      error: {
        required: 'Please enter the name on your card',
        invalid: 'Please enter the full name exactly as it appears on your card'
      }
    }
  }
}

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

Refer to Mount the Checkout for the complete mounting flow.

Test custom validation messages thoroughly to ensure clarity and accuracy.

Use the `CheckoutTranslate` Interface

The CheckoutTranslate interface defines all customizable text elements:

CheckoutTranslate['card']

Text content for card payment form elements.

Show Card Properties

string

Generic message shown when a required card field is empty.

CheckoutTranslate['card']['number']

Card number field text and error messages.

Show Number Properties

string

Label text for the card number input.

CheckoutTranslate['card']['number']['error']

Error messages for card number validation.

Show Error Properties

string

Message when format is invalid.

string

Message when entry is incomplete.

string

Message when card type is not accepted.

CheckoutTranslate['card']['expiry']

Expiry date field text and error messages.

Show Expiry Properties

string

Label text for expiry field.

string

Placeholder text (e.g., “MM/YY”).

CheckoutTranslate['card']['expiry']['error']

Error messages for expiry validation.

CheckoutTranslate['card']['cvc']

CVC/CVV security code field text and error messages.

Show CVC Properties

string

Label text for CVC input.

string

Placeholder text (e.g., “CVC”).

CheckoutTranslate['card']['cvc']['error']

Error messages for CVC validation.

CheckoutTranslate['card']['name']

Cardholder name field text.

Show Name Properties

string

Label text for cardholder name.

string

Placeholder text for name input.

CheckoutTranslate['card']['pay']

Payment button text configuration.

Show Pay Properties

string

Text displayed on the main payment button.

CheckoutTranslate['card']['compact']

Compact view button text configuration.

Show Compact Properties

string

Text for payment method selection button.

CheckoutTranslate['status']

Status messages for payment completion and errors.

Show Status Properties

string

Message displayed when payment fails.

string

Message displayed when the checkout session is invalid or expired.

string

Message displayed when the 3DS authentication step returns an error.

CheckoutTranslate['errors']

Optional processor error overrides that map gateway decline codes to custom copy.

Show Error Override Properties

string

Message for a generic issuer decline (do_not_honor).

string

Message when the card has insufficient funds.

string

Message when a card spending limit is exceeded.

string

Message when the card is expired.

string

Message when the card number fails validation.

string

Message when the processor declines due to suspected fraud.

string

Message when extra authentication (3DS/SCA) is required.

string

Message when the issuer is offline and cannot approve the payment.

string

Message when the card is reported lost or stolen.

string

Message when the secure payment payload is invalid.

string

Fallback message when the payment is declined for another reason.

3DS Authentication Failures

When the 3DS (3D Secure) authentication flow encounters an error, the checkout surfaces the authenticationFailed status message. The payment status payload contains a decline_code that distinguishes between:

payment_attempt_authentication_cancelled: Customer explicitly closed the challenge window, abandoned it before timeout, or the challenge window was left open beyond the 10-minute timeout
payment_attempt_authentication_failed: Issuer rejected the authentication attempt (wrong code, failed biometric verification, issuer decline, etc.).

Use the status_reason.decline_code in your payment status callbacks to customize messaging based on the failure type. See the 3D Secure guide for complete API response examples and detailed explanations of each scenario.

Workflows can still block a payment after 3DS. In that case the SDK receives status: "blocked" with the default “The payment was blocked by the workflow settings.” copy—branch on this separately from regular declined/failed outcomes.

Supported Languages

Show Complete Language List (30+ languages)

🇺🇸 English

en - English

🇪🇸 Spanish

es - Español

🇫🇷 French

fr - Français

🇩🇪 German

de - Deutsch

🇮🇹 Italian

it - Italiano

🇵🇹 Portuguese

pt - Português

🇳🇱 Dutch

nl - Nederlands

🇵🇱 Polish

pl - Polski

🇺🇦 Ukrainian

ua - Українська

🇷🇺 Russian

ru - Русский

🇨🇳 Chinese

zh - 中文

🇯🇵 Japanese

ja - 日本語

🇰🇷 Korean

ko - 한국어

🇦🇪 Arabic

ar - العربية

🇹🇭 Thai

th - ไทย

🇻🇳 Vietnamese

vi - Tiếng Việt

🇸🇪 Swedish

sv - Svenska

🇳🇴 Norwegian

no - Norsk

🇩🇰 Danish

da - Dansk

🇫🇮 Finnish

fi - Suomi

🇨🇿 Czech

cs - Čeština

🇭🇺 Hungarian

hu - Magyar

🇷🇴 Romanian

ro - Română

🇬🇷 Greek

el - Ελληνικά

🇧🇬 Bulgarian

bg - Български

🇭🇷 Croatian

hr - Hrvatski

🇸🇰 Slovak

sk - Slovenčina

🇸🇮 Slovenian

sl - Slovenščina

🇪🇪 Estonian

et - Eesti

🇱🇻 Latvian

lv - Latviešu

🇱🇹 Lithuanian

lt - Lietuvių

🇮🇩 Indonesian

id - Bahasa Indonesia

🇲🇾 Malay

ms - Bahasa Melayu

🇵🇭 Filipino

fil - Filipino

🇹🇷 Turkish

tr - Türkçe

🇲🇹 Maltese

mt - Malti

For locales with regional variants (e.g., pt-BR), the PayNext SDK falls back to the base language when a region-specific string is not provided.

Apply Best Practices

Right-to-Left (RTL) Support

RTL languages automatically receive proper layout and text direction:

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

Refer to Mount the Checkout for the complete mounting flow.

No extra configuration is required. Provide locale="ar" (or let the browser detection pick it up) and the PayNext SDK will render RTL.

Multi-Language Support

Handle multiple languages dynamically with language switching:

custom component

import { useEffect, useState } from 'react'
import { PayNextCheckout, type DeepPartial, type CheckoutTranslate, type PayNextConfig } from '@paynext/sdk'

const translations: Record<string, DeepPartial<CheckoutTranslate>> = {
  en: {
    card: {
      required: 'Enter all required card details.',
      pay: { button: 'Pay Now' }
    },
    status: {
      error: 'Something went wrong. Try again.',
      invalidSession: 'Session expired. Refresh to continue.'
    }
  },
  es: {
    card: {
      required: 'Completa todos los campos obligatorios.',
      pay: { button: 'Pagar Ahora' }
    },
    status: {
      error: 'No se pudo procesar el pago. Inténtalo de nuevo.',
      invalidSession: 'La sesión expiró. Actualiza para continuar.'
    }
  },
  fr: {
    card: {
      required: 'Veuillez remplir tous les champs obligatoires.',
      pay: { button: 'Payer Maintenant' }
    },
    status: {
      error: 'Impossible de traiter le paiement. Réessayez.',
      invalidSession: 'La session a expiré. Actualisez pour continuer.'
    }
  },
  de: {
    card: {
      required: 'Bitte füllen Sie alle Pflichtfelder aus.',
      pay: { button: 'Jetzt Bezahlen' }
    },
    status: {
      error: 'Zahlung fehlgeschlagen. Bitte versuchen Sie es erneut.',
      invalidSession: 'Sitzung abgelaufen. Bitte aktualisieren.'
    }
  }
}

const clientToken = 'your-client-token' // Replace with token from your backend
const baseConfig: PayNextConfig = {
  clientToken,
  environment: 'sandbox',
  apiVersion: '1.0.0',
  /* other options */
}

const MultiLanguageCheckout = () => {
  const [locale, setLocale] = useState('en')
  const containerId = 'paynext-checkout'

  useEffect(() => {
    const checkout = new PayNextCheckout()
    checkout
      .mount(containerId, {
        ...baseConfig,
        locale,
        translate: translations[locale],
      })
      .catch(console.error)

    return () => {
      checkout.unmount().catch(console.error)
    }
  }, [locale])

  return (
    <div>
      <select
        value={locale}
        onChange={(event) => setLocale(event.target.value)}
        className="mb-4 p-2 border rounded"
      >
        <option value="en">🇺🇸 English</option>
        <option value="es">🇪🇸 Español</option>
        <option value="fr">🇫🇷 Français</option>
        <option value="de">🇩🇪 Deutsch</option>
      </select>

      <div id={containerId} />
    </div>
  )
}

export default MultiLanguageCheckout

The SDK will automatically use built-in translations for any text you don’t customize, ensuring complete language coverage.

Always provide fallbacks for missing translations to prevent broken user experiences in production.

Text Quality Guidelines

Write clear, actionable text that helps users complete their payment: Error messages:

Explain what went wrong and how to fix it
Use positive, helpful language instead of blame
Provide specific guidance when possible
Keep messages concise but complete

Button labels:

Use action-oriented language (“Complete Purchase” vs “Submit”)
Match your site’s existing button patterns
Consider cultural preferences for different markets
Test different labels to optimize conversion

Fallback Strategy

Implement proper fallbacks for missing translations:

Partial overrides: Unspecified strings use built-in translations
Locale fallbacks: Regional variants fall back to the base language
Default language: System falls back to English if locale is unsupported
Error handling: Graceful degradation if translation loading fails

Common Pitfalls

Avoid these text customization mistakes:

Inconsistent terminology across your application and checkout form
Overly long text that breaks mobile layouts
Missing context in error messages that confuses users
Cultural insensitivity when translating for different markets
Technical jargon that doesn’t match your brand voice

Always test custom text across different screen sizes and with actual users from your target markets.

​When and Why to Customize Text

Complete Control

Multi-Language Support

RTL Language Support

Partial Overrides

​Implement Language Detection

​Override the Global Error Banner

​Customize Text (Examples)

​Use the CheckoutTranslate Interface

​3DS Authentication Failures

​Supported Languages

🇺🇸 English

🇪🇸 Spanish

🇫🇷 French

🇩🇪 German

🇮🇹 Italian

🇵🇹 Portuguese

🇳🇱 Dutch

🇵🇱 Polish

🇺🇦 Ukrainian

🇷🇺 Russian

🇨🇳 Chinese

🇯🇵 Japanese

🇰🇷 Korean

🇦🇪 Arabic

🇹🇭 Thai

🇻🇳 Vietnamese

🇸🇪 Swedish

🇳🇴 Norwegian

🇩🇰 Danish

🇫🇮 Finnish

🇨🇿 Czech

🇭🇺 Hungarian

🇷🇴 Romanian

🇬🇷 Greek

🇧🇬 Bulgarian

🇭🇷 Croatian

🇸🇰 Slovak

🇸🇮 Slovenian

🇪🇪 Estonian

🇱🇻 Latvian

🇱🇹 Lithuanian

🇮🇩 Indonesian

🇲🇾 Malay

🇵🇭 Filipino

🇹🇷 Turkish

🇲🇹 Maltese

​Apply Best Practices

​Right-to-Left (RTL) Support

​Multi-Language Support

​Text Quality Guidelines

​Fallback Strategy

​Common Pitfalls

When and Why to Customize Text

Implement Language Detection

Override the Global Error Banner

Customize Text (Examples)

Use the `CheckoutTranslate` Interface

3DS Authentication Failures

Supported Languages

Apply Best Practices

Right-to-Left (RTL) Support

Multi-Language Support

Text Quality Guidelines

Fallback Strategy

Common Pitfalls