@checkout.com/checkout-react-native-components

Checkout React Native Components

• 🚀 Quick Start
  • Installation
  • Platform Setup
• 🧩 Components Overview
• ⚙️ Core Configuration
  • CheckoutProvider Setup
  • Configuration Options
• 📖 Component Reference
  • Flow Component
  • Card Component
  • Apple Pay Component
  • Google Pay Component
• 🔧 Advanced Features
  • Imperative API
• 🎨 Customization
  • Color Tokens
  • Border Radius
  • Localization
• 📡 Event Handling
  • Component Callbacks
  • Error Types
  • Tokenization Result
• 📄 License

For detailed integration steps, refer to our official documentation ↗️ .

🚀 Quick Start

Installation

Install the package using your preferred package manager:

npm install @checkout.com/checkout-react-native-components

yarn add @checkout.com/checkout-react-native-components

Platform Setup

This package supports both React Native architectures (New Architecture/Fabric and Old Architecture/Paper) out of the box.

📱 iOS Setup

cd ios
pod install

🤖 Android Setup

Add the following repositories to your app's settings.gradle:

dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.PREFER_SETTINGS)
    repositories {
        google()
        mavenCentral()
        maven { url = uri("https://jitpack.io") }
        maven { url = uri("https://maven.fpregistry.io/releases") }
    }
}

Or add the allProjects block to the project build.gradle:

allprojects {
  repositories {
    google()
    mavenCentral()
    maven { url 'https://maven.fpregistry.io/releases' }
    maven { url 'https://www.jitpack.io' }
  }
}

To enable Google Pay payments the following metadata tag must be added to your AndroidManifest.xml:

<meta-data
    android:name="com.google.android.gms.wallet.api.enabled"
    android:value="true" />

While not mandatory, we recommend setting android:allowBackup to false in your AndroidManifest.xml. Failing to set it to false or to override our default value with your own will result in a manifest merge error.

Requirements:

• New Arch: Android Studio Ladybug 2024.2.2
• Old Arch: Android Studio Koala 2024.1.1

💡 Tip: Use JetBrains Toolbox for easy Android Studio version management.

Expo Setup

Our package cannot run in Expo Go. Instead, you need to run:

npx expo prebuild

This command compiles your app with our package included.

For Android, the repositories step above is a hard requirement to resolve dependencies. Our package provides a general-purpose plugin that appends the repositories defined in the Android Setup block above. The plugin can also append the Google Pay tag to the AndroidManifest.xml if required.

If your app already uses custom plugins that modify build.gradle or AndroidManifest.xml, we recommend extending your existing plugin or creating an additional plugin to customize adding the repositories block to fit your use case. You can find documentation on writing Expo plugins here.

The android:allowBackup tag and plugins can be set in app.json like so:

"android": {
  "allowBackup": false
},
"plugins": [
  [
    "@checkout.com/checkout-react-native-components",
    {
      "enableGooglePay": true
    }
  ]
]

🧩 Components Overview

Component	Description	Platform	Key Features
Flow	Complete payment flow with multiple payment methods	iOS/Android	3DS support, dynamic payment methods, built-in validation
Card	Secure card input form	iOS/Android	Card validation, tokenization, custom styling
Apple Pay	Native Apple Pay integration	iOS only	Seamless iOS payment experience
Google Pay	Native Google Pay integration	Android only	Seamless Android payment experience

⚙️ Core Configuration

CheckoutProvider Setup

Wrap your payment screen with CheckoutProvider to enable payment functionality.

Create a Payment Session and pass it to CheckoutProvider.

import {
  CheckoutProvider,
  CheckoutConfiguration,
  Environment,
  Locale
} from '@checkout.com/checkout-react-native-components';

const config: CheckoutConfiguration = {
  publicKey: 'pk_test_your_public_key',
  environment: 'sandbox', // or 'production'
  locale: Locale.en_GB,
  merchantIdentifier: 'merchant.com.your-app.name', // Required for Apple Pay
  translations: {
    [Locale.en_GB]: {
      cardNumber: 'Card Number',
      payButtonPay: 'Pay Now'
    }
  },
  style: {
    colorTokensMain: {
      primary: '#186AFF',
      background: '#FFFFFF',
      border: '#E3E8F2',
      error: '#E01E5A'
    },
    borderButtonRadius: 12,
    borderFormRadius: 8
  }
};

export default function PaymentScreen() {
  const [paymentSession, setPaymentSession] = useState({
    id: '',
    payment_session_secret: ''
  });

  useEffect(() => {
    fetchPaymentSession().then((data) => {
      setPaymentSession(data);
    });
  }, []);

  return (
    <CheckoutProvider 
      config={config}
      onSuccess={(paymentMethod, paymentID) => {
        console.log('Payment successful:', { paymentMethod, paymentID });
      }}
      onError={(error) => {
        console.error('Payment error:', error);
      }}
      paymentSession={paymentSession}
    >
      {/* Your app components */}
    </CheckoutProvider>
  );
}

📝 Configuration Options

Property	Type	Required	Description
publicKey	string	✅	Your Checkout.com public API key
environment	'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

📖 Component Reference

Flow Component

The Flow component provides a complete payment experience with support for multiple payment methods, 3D Secure, and dynamic payment method display.

🔧 Flow Configuration & Usage

Basic Usage

import { Flow } from '@checkout.com/checkout-react-native-components';

const PaymentScreen = () => {
  return (
    <CheckoutProvider config={config} paymentSession={paymentSession}>
      <Flow style={{ marginVertical: 20 }} />
    </CheckoutProvider>
  );
};

Imperative API Usage

const PaymentScreen = () => {
  const flowRef = useRef<FlowRef>(null);

  const handleSubmit = () => {
    flowRef.current?.submit(); // Process payment
  };

  const handleTokenize = () => {
    flowRef.current?.tokenize(); // Tokenize card
  };

  return (
    <CheckoutProvider config={config} paymentSession={paymentSession}>
      <Flow 
        ref={flowRef}
        config={{ showPayButton: false }} // Hide built-in pay button
      />
      <Button title="Pay" onPress={handleSubmit} />
      <Button title="Tokenize Card" onPress={handleTokenize} />
    </CheckoutProvider>
  );
};

Flow Props

Property	Type	Required	Description
config	FlowConfig	❌	Flow-specific configuration
style	ViewStyle | ViewStyle[]	❌	React Native styling
ref	FlowRef	❌	Imperative API reference

FlowConfig Options

Property	Type	Default	Description
showPayButton	boolean	true	Show/hide the built-in pay button
paymentButtonAction	'payment' | 'tokenize'	'payment'	Action when pay button is pressed

Card Component

The Card component provides a secure card input form ideal for custom checkout implementations.

💳 Card Configuration & Usage

Basic Usage

import { Card, CardRef } from '@checkout.com/checkout-react-native-components';

const CardPaymentScreen = () => {
  const cardRef = useRef<CardRef>(null);
  
  const handleSubmit = () => {
    cardRef.current?.submit();
  };

  return (
    <CheckoutProvider config={config} paymentSession={paymentSession}>
      <Card 
        ref={cardRef}
        config={{ showPayButton: false }}
      />
    </CheckoutProvider>
  );
};

Card Props

Property	Type	Required	Description
config	CardConfig	❌	Card-specific configuration
style	ViewStyle | ViewStyle[]	❌	React Native styling
ref	CardRef	❌	Imperative API reference

CardConfig Options

Property	Type	Default	Description
showPayButton	boolean	true	Show/hide the built-in pay button
paymentButtonAction	'payment' | 'tokenize'	'payment'	Action when pay button is pressed

Apple Pay Component

The Apple Pay component provides native Apple Pay integration for iOS devices.

🍎 Apple Pay Configuration & Usage

Basic Usage

import { ApplePay, CheckoutProvider } from '@checkout.com/checkout-react-native-components';

const PaymentScreen = () => {
  return (
    <CheckoutProvider 
      config={{
        ...config,
        merchantIdentifier: 'merchant.com.your-app.name' // Required!
      }} 
      paymentSession={paymentSession}
    >
      <ApplePay style={{ height: 60, marginVertical: 10 }} />
    </CheckoutProvider>
  );
};

Apple Pay Props

Property	Type	Required	Description
style	ViewStyle | ViewStyle[]	❌	React Native styling

📝 Note: Apple Pay requires a valid merchantIdentifier in your CheckoutConfiguration and is only available on iOS devices.

Google Pay Component

The Google Pay component provides native Google Pay integration for Android devices.

🤖 Google Pay Configuration & Usage

Basic Usage

import { CheckoutProvider, GooglePay } from '@checkout.com/checkout-react-native-components';

const PaymentScreen = () => {
  return (
    <CheckoutProvider config={config} paymentSession={paymentSession}>
      <GooglePay />
    </CheckoutProvider>
  );
};

Google Pay Props

Property	Type	Required	Description
config	GooglePayConfig	❌	Google Pay configuration (reserved for future use)
style	ViewStyle | ViewStyle[]	❌	React Native styling

📝 Note: Google Pay is only available on Android devices.

🔧 Advanced Features

Imperative API

Both Flow and Card components support imperative APIs for programmatic control:

import { CheckoutProvider, Card, Flow, FlowRef, CardRef } from '@checkout.com/checkout-react-native-components';

const PaymentScreen = () => {
  const flowRef = useRef<FlowRef>(null);
  const cardRef = useRef<CardRef>(null);

  const processPayment = async () => {
    flowRef.current?.submit();
  };

  const tokenizeCard = async () => {
    cardRef.current?.tokenize();
  };

  return (
    <CheckoutProvider config={config} paymentSession={paymentSession}>
      <Flow ref={flowRef} config={{ showPayButton: false }} />
      <Card ref={cardRef} config={{ showPayButton: false }} />
      
      <Button title="Process Payment" onPress={processPayment} />
      <Button title="Save Card" onPress={tokenizeCard} />
    </CheckoutProvider>
  );
};

🎨 Customization

🎨 Complete Color Token Reference

const customStyle = {
  colorTokensMain: {
    // Primary brand color
    primary: '#186AFF',
    
    // Background colors
    background: '#FFFFFF',
    formBackground: '#F7F9FC',
    
    // Border colors
    border: '#E3E8F2',
    formBorder: '#C8D1E0',
    outline: '#91B2EE',
    
    // State colors
    error: '#E01E5A',
    success: '#1AA27B',
    disabled: '#B0B0B0',
    
    // Text colors
    secondary: '#545F7A',
    inverse: '#FFFFFF',
    
    // Action colors
    action: '#186AFF',
    
    // Android specific
    scrolledContainer: '#F0F0F0' // Android only
  }
};

📏 Border Radius

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

🌍 Supported Locales & Custom Translations

Supported Locales

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

Translations Interface

All available translation keys with their descriptions:

export type Translations = {
  addBillingAddress?: string;
  addAddress?: string;
  address?: string;
  addressLine1?: string;
  addressLine2?: string;
  billingAddress?: string;
  card?: string;
  cardExpiryDate?: string;
  cardExpiryDateIncomplete?: string;
  cardExpiryDateInvalid?: string;
  cardExpiryDatePlaceholderMonth?: string;
  cardExpiryDatePlaceholderYear?: string;
  cardHolderName?: string;
  cardNumber?: string;
  cardNumberInvalid?: string;
  cardNumberNotSupported?: string;
  cardSecurityCode?: string;
  cardSecurityCodeInvalid?: string;
  cardSecurityCodePlaceholder?: string;
  city?: string;
  confirm?: string;
  country?: string;
  selectCountry?: string;
  editAddress?: string;
  email?: string;
  emailFormatInvalid?: string;
  firstName?: string;
  formRequired?: string;
  lastName?: string;
  insufficientCharacters?: string;
  noMatchesFound?: string;
  optional?: string;
  payButtonPay?: string;
  payButtonPaymentComplete?: string;
  payButtonPaymentProcessing?: string;
  paymentDeclinedInvalidCustomerData?: string;
  paymentDeclinedInvalidPaymentSessionData?: string;
  paymentDeclinedMerchantMisconfiguration?: string;
  paymentDeclinedNotEnoughFunds?: string;
  paymentDeclinedTryAgain?: string;
  phoneNumber?: string;
  search?: string;
  state?: string;
  trySearchingWithAnotherTerm?: string;
  useShippingAsBilling?: string;
  zip?: string;
  preferredSchemeCta?: string;
  preferredSchemeDescription?: string;
  selectState?: string;
};

Custom Translations Example

const customTranslations = {
  [Locale.en_GB]: {
    // Address and billing
    addBillingAddress: 'Add Billing Address',
    addAddress: 'Add Address',
    address: 'Address',
    addressLine1: 'Address Line 1',
    addressLine2: 'Address Line 2',
    billingAddress: 'Billing Address',
    
    // Card form labels
    card: 'Card',
    cardNumber: 'Card Number',
    cardExpiryDate: 'MM/YY',
    cardExpiryDatePlaceholderMonth: 'MM',
    cardExpiryDatePlaceholderYear: 'YY',
    cardSecurityCode: 'CVV',
    cardSecurityCodePlaceholder: 'CVV',
    cardHolderName: 'Cardholder Name',
    
    // Personal information
    firstName: 'First Name',
    lastName: 'Last Name',
    email: 'Email Address',
    phoneNumber: 'Phone Number',
    
    // Location fields
    city: 'City',
    state: 'State/Province',
    zip: 'ZIP/Postal Code',
    country: 'Country',
    selectCountry: 'Select Country',
    selectState: 'Select State',
    
    // Actions and buttons
    payButtonPay: 'Pay Now',
    payButtonPaymentProcessing: 'Processing...',
    payButtonPaymentComplete: 'Payment Complete',
    confirm: 'Confirm',
    editAddress: 'Edit Address',
    search: 'Search',
    
    // Validation and error messages
    formRequired: 'This field is required',
    cardNumberInvalid: 'Invalid card number',
    cardNumberNotSupported: 'Card type not supported',
    cardExpiryDateIncomplete: 'Expiry date incomplete',
    cardExpiryDateInvalid: 'Invalid expiry date',
    cardSecurityCodeInvalid: 'Invalid security code',
    emailFormatInvalid: 'Invalid email format',
    insufficientCharacters: 'Insufficient characters',
    
    // Payment errors
    paymentDeclinedTryAgain: 'Payment declined. Please try again.',
    paymentDeclinedNotEnoughFunds: 'Insufficient funds',
    paymentDeclinedInvalidCustomerData: 'Invalid payment details',
    paymentDeclinedInvalidPaymentSessionData: 'Invalid payment session data',
    paymentDeclinedMerchantMisconfiguration: 'Merchant configuration error',
    
    // Search and selection
    noMatchesFound: 'No matches found',
    trySearchingWithAnotherTerm: 'Try searching with another term',
    
    // Miscellaneous
    optional: 'Optional',
    useShippingAsBilling: 'Use shipping address as billing address',
    preferredSchemeCta: 'Select Preferred Scheme',
    preferredSchemeDescription: 'Please select your preferred card scheme'
  }
};

📡 Event Handling

📋 Complete Event Reference

const eventHandlers = {
  // Component lifecycle
  onReady: (paymentMethod: string) => {
    console.log('Component ready for:', paymentMethod);
  },
  
  // Form validation
  onChange: (paymentMethod: string, isValid: boolean) => {
    console.log('Form state changed:', { paymentMethod, isValid });
    // Update UI based on form validity
  },
  
  // Payment submission
  onSubmit: (paymentMethod: string) => {
    console.log('Payment submitted for:', paymentMethod);
    // Show loading state
  },
  
  // Tokenization
  onTokenized: (tokenizationResult: TokenizationResult) => {
    console.log('Card tokenized:', tokenizationResult);
    // Save token for future use
  },
  
  // Payment success
  onSuccess: (paymentMethod: string, paymentID: string) => {
    console.log('Payment successful:', { paymentMethod, paymentID });
    // Navigate to success screen
  },
  
  // Error handling
  onError: (error: Error) => {
    console.error('Payment error:', error);
    // Show error message to user
  },  
};

<CheckoutProvider {...eventHandlers}>
  {/* Components */}
</CheckoutProvider>

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.