Configuration

Last updated: October 6, 2025

The Checkout React Native Components library provides extensive configuration options to customize the appearance and behavior of your payment components.

The main configuration object that defines the behavior and appearance of your payment components.


1import { CheckoutConfiguration, Environment, Locale } from '@checkout.com/checkout-react-native-components';
2
3const config: CheckoutConfiguration = {
4  publicKey: 'pk_test_your_public_key',
5  environment: Environment.sandbox,
6  locale: Locale.en_GB,
7  merchantIdentifier: 'merchant.com.your-app.name',
8  translations: {
9  [Locale.en_GB]: {
10    cardNumber: 'Card Number',
11    payButtonPay: 'Pay Now'
12  }
13 },
14 style: {
15  colorTokensMain: {
16    primary: '#186AFF',
17    background: '#FFFFFF',
18    border: '#E3E8F2',
19    error: '#E01E5A'
20  },
21  borderButtonRadius: 12,
22  borderFormRadius: 8
23 }
24};

Property	Type	Description
`publicKey` required	`string`	Your Checkout.com public API key
`environment` required	`'sandbox' \| 'production'`	Environment for API calls
`locale`	`string`	Locale for UI text (defaults to English)
`merchantIdentifier`	`string`	Apple Pay merchant identifier
`translations`	`Record<string, Translations>`	Custom text translations
`style`	`Style`	UI customization options

Customize the appearance of your payment components with color tokens:


1const customStyle = {
2  colorTokensMain: {
3    // Primary brand color
4    primary: '#186AFF',
5
6    // Background colors
7    background: '#FFFFFF',
8    formBackground: '#F7F9FC',
9
10    // Border colors
11    border: '#E3E8F2',
12    formBorder: '#C8D1E0',
13    outline: '#91B2EE',
14
15    // State colors
16    error: '#E01E5A',
17    success: '#1AA27B',
18    disabled: '#B0B0B0',
19
20    // Text colors
21    secondary: '#545F7A',
22    inverse: '#FFFFFF',
23
24    // Action colors
25    action: '#186AFF',
26
27    scrolledContainer: '#F0F0F0' // Android only
28  }
29};

Key	Format	Description
`primary`	`#RRGGBB`	Primary brand color for buttons and interactive elements
`background`	`#RRGGBB`	Main background color
`formBackground`	`#RRGGBB`	Background color for form fields
`border`	`#RRGGBB`	Default border color
`formBorder`	`#RRGGBB`	Border color for form fields
`outline`	`#RRGGBB`	Focus outline color
`error`	`#RRGGBB`	Error state color
`success`	`#RRGGBB`	Success state color
`disabled`	`#RRGGBB`	Disabled element color
`secondary`	`#RRGGBB`	Secondary text color
`inverse`	`#RRGGBB`	Inverse text color (for dark backgrounds)
`action`	`#RRGGBB`	Action button color
`scrolledContainer`	`#RRGGBB`	Android-specific scrolled container color

Customize the border radius of buttons and form elements:


1const customBorders = {
2  borderButtonRadius: 12,  // Button border radius
3  borderFormRadius: 8      // Form field border radius
4};

Property	Type	Default	Description
`borderFormRadius`	`number`	`8`	Border radius for form fields
`borderButtonRadius`	`number`	`12`	Border radius for buttons

The library supports multiple locales with customizable translations.


1enum Locale {
2  ar = 'ar',           // Arabic
3  da_DK = 'da-DK',     // Danish
4  de_DE = 'de-DE',     // German
5  el = 'el',           // Greek
6  en_GB = 'en-GB',     // English (UK)
7  es_ES = 'es-ES',     // Spanish
8  fi_FI = 'fi-FI',     // Finnish
9  fil_PH = 'fil-PH',   // Filipino
10  fr_FR = 'fr-FR',     // French
11  hi_IN = 'hi-IN',     // Hindi
12  id_ID = 'id-ID',     // Indonesian
13  it_IT = 'it-IT',     // Italian
14  ja_JP = 'ja-JP',     // Japanese
15  ms_MY = 'ms-MY',     // Malay
16  nb_NO = 'nb-NO',     // Norwegian
17  nl_NL = 'nl-NL',     // Dutch
18  pt_PT = 'pt-PT',     // Portuguese
19  sv_SE = 'sv-SE',     // Swedish
20  th_TH = 'th-TH',     // Thai
21  vi_VN = 'vi-VN',     // Vietnamese
22  zh_CN = 'zh-CN',     // Chinese (Simplified)
23  zh_HK = 'zh-HK',     // Chinese (Hong Kong)
24  zh_TW = 'zh-TW'      // Chinese (Traditional)
25}


1const customTranslations = {
2  [Locale.en_GB]: {
3    // Address and billing
4    addBillingAddress: 'Add Billing Address',
5    addAddress: 'Add Address',
6    address: 'Address',
7    addressLine1: 'Address Line 1',
8    addressLine2: 'Address Line 2',
9    billingAddress: 'Billing Address',
10
11    // Card form labels
12    card: 'Card',
13    cardNumber: 'Card Number',
14    cardExpiryDate: 'MM/YY',
15    cardExpiryDatePlaceholderMonth: 'MM',
16    cardExpiryDatePlaceholderYear: 'YY',
17    cardSecurityCode: 'CVV',
18    cardSecurityCodePlaceholder: 'CVV',
19    cardHolderName: 'Cardholder Name',
20
21    // Personal information
22    firstName: 'First Name',
23    lastName: 'Last Name',
24    email: 'Email Address',
25    phoneNumber: 'Phone Number',
26
27    // Location fields
28    city: 'City',
29    state: 'State/Province',
30    zip: 'ZIP/Postal Code',
31    country: 'Country',
32    selectCountry: 'Select Country',
33    selectState: 'Select State',
34
35    // Actions and buttons
36    payButtonPay: 'Pay Now',
37    payButtonPaymentProcessing: 'Processing...',
38    payButtonPaymentComplete: 'Payment Complete',
39    confirm: 'Confirm',
40    editAddress: 'Edit Address',
41    search: 'Search',
42
43    // Validation and error messages
44    formRequired: 'This field is required',
45    cardNumberInvalid: 'Invalid card number',
46    cardNumberNotSupported: 'Card type not supported',
47    cardExpiryDateIncomplete: 'Expiry date incomplete',
48    cardExpiryDateInvalid: 'Invalid expiry date',
49    cardSecurityCodeInvalid: 'Invalid security code',
50    emailFormatInvalid: 'Invalid email format',
51    insufficientCharacters: 'Insufficient characters',
52
53    // Payment errors
54    paymentDeclinedTryAgain: 'Payment declined. Please try again.',
55    paymentDeclinedNotEnoughFunds: 'Insufficient funds',
56    paymentDeclinedInvalidCustomerData: 'Invalid payment details',
57    paymentDeclinedInvalidPaymentSessionData: 'Invalid payment session data',
58    paymentDeclinedMerchantMisconfiguration: 'Merchant configuration error',
59
60    // Search and selection
61    noMatchesFound: 'No matches found',
62    trySearchingWithAnotherTerm: 'Try searching with another term',
63
64    // Miscellaneous
65    optional: 'Optional',
66    useShippingAsBilling: 'Use shipping address as billing address',
67    preferredSchemeCta: 'Select Preferred Scheme',
68    preferredSchemeDescription: 'Please select your preferred card scheme'
69  }
70};

Configure the behavior of the Flow component:


1const flowConfig = {
2  showPayButton: false,           // Hide built-in pay button
3  paymentButtonAction: 'tokenize' // Tokenize instead of submitting the payment
4};
5
6<Flow config={flowConfig} />

Configure the behavior of the Card component:


1const cardConfig = {
2  showPayButton: true,           // Show built-in pay button
3  paymentButtonAction: 'payment' // Process payment when pressed
4};
5
6<Card config={cardConfig} />


1import React, { useRef, useState, useEffect } from 'react';
2import {
3  CheckoutProvider,
4  CheckoutConfiguration,
5  Flow,
6  Environment,
7  Locale,
8} from '@checkout.com/checkout-react-native-components';
9
10const config: CheckoutConfiguration = {
11  publicKey: 'pk_test_your_public_key',
12  environment: Environment.sandbox,
13  locale: Locale.en_GB,
14  merchantIdentifier: 'merchant.com.your-app.name',
15  translations: {
16    [Locale.en_GB]: {
17      cardNumber: 'Card Number',
18      payButtonPay: 'Pay Now',
19      formRequired: 'This field is required'
20    }
21  },
22  style: {
23    colorTokensMain: {
24      primary: '#186AFF',
25      background: '#FFFFFF',
26      formBackground: '#F7F9FC',
27      border: '#E3E8F2',
28      formBorder: '#C8D1E0',
29      outline: '#91B2EE',
30      error: '#E01E5A',
31      success: '#1AA27B',
32      disabled: '#B0B0B0',
33      secondary: '#545F7A',
34      inverse: '#FFFFFF',
35      action: '#186AFF'
36    },
37    borderButtonRadius: 12,
38    borderFormRadius: 8
39  }
40};
41
42export default function PaymentScreen() {
43  const [paymentSession, setPaymentSession] = useState(null);
44
45  useEffect(() => {
46    // Fetches the payment session from your server
47    fetchPaymentSession().then(setPaymentSession);
48  }, []);
49
50  return (
51    <CheckoutProvider
52      config={config}
53      paymentSession={paymentSession}
54      onSuccess={(paymentMethod, paymentID) => {
55        console.log('Payment successful:', { paymentMethod, paymentID });
56      }}
57      onError={(error) => {
58        console.error('Payment error:', error);
59      }}
60    >
61      <Flow />
62    </CheckoutProvider>
63  );
64}

Configuration

CheckoutConfiguration

Configuration Properties

Style Configuration

Color Tokens

Complete Color Token Reference

Border Radius

Localization

Supported Locales

Custom Translations

Component-Specific Configuration

FlowConfig

CardConfig

Example: Complete Configuration