@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") }
    }
}

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.

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