How to Integrate Drop-in

Drop-in is a pre-built UI that bundles all your payment methods into a single, ready-to-mount component. No per method integration required.

Prerequisites

@payrails/react-native-sdk installed.
A backend endpoint that calls /client/init and returns the session response.
See the Getting Started guide for provider setup.

Steps

1. Mount the Drop-in

Pass the full /client/init response to config. The Drop-in will not render without a valid config.

import { PayrailsDropin } from '@payrails/react-native-sdk';

<PayrailsDropin
  config={initResponse}
  events={{
    onAuthorizeSuccess: () => console.log('Success'),
    onAuthorizeFailure: (failure) => console.log('Payment failed', failure),
  }}
/>

2. Handle payment outcomes

Use events.onAuthorizeSuccess and events.onAuthorizeFailure to navigate or show feedback. Always confirm the final payment status server-side via webhook — do not rely solely on client callbacks.

Customising the Drop-in

Styles: pass a DropinStyles object to the styles property. See the Drop-in API Reference for the full type.
Payment method visibility: use paymentMethodsConfiguration to show or hide logos, stored instruments, and cardholder name. See the Drop-in API Reference.
Translations: pass a Translations object to localise all labels. See the Drop-in API Reference.

How to Use Elements

Each Element handles a single payment method — drop it anywhere in your UI for full control over layout and placement.

Elements must be rendered inside a PayrailsProvider. See the Getting Started guide for provider setup.
For configuration options for each element, see the Elements API Reference.

How to Pay with a Stored Card

import React, { useState } from 'react';
import {
  PayWithCardButton,
  useStoredCardInstruments,
  PayrailsProvider,
} from '@payrails/react-native-sdk';

export function StoredCardsExample() {
  const [loading, setLoading] = useState(false);
  const storedCards = useStoredCardInstruments();

  return (
    <PayrailsDropin config={initResponse}
      {storedCards.map((card) => (
        <PayWithCardButton
          key={card.id}
          instrument={card}
          disabled={loading}
          onAuthorizeSuccess={() => console.log('Payment succeeded')}
          onAuthorizeFailure={(failure) =>
            console.log('Payment failed', failure)
          }
          onRequestProgressChange={(inProgress) => setLoading(inProgress)}
        />
      ))}
    </PayrailsProvider>
  );
}

How to Pay with a New Card

import React from 'react';
import {
  TokenizationForm,
  CardNumberElement,
  CardHolderNameElement,
  ExpirationDateElement,
  CvvElement,
  PayWithNewCardButton,
  PayrailsProvider,
} from '@payrails/react-native-sdk';

export function NewCardPaymentExample() {
  return (
    <PayrailsDropin config={initResponse}
      <TokenizationForm>
        <CardNumberElement />
        <CardHolderNameElement />
        <ExpirationDateElement />
        <CvvElement />
        <PayWithNewCardButton
          title="Pay"
          shouldSaveCard={true}
          onAuthorizeSuccess={() => console.log('Payment succeeded')}
          onAuthorizeFailure={(failure) =>
            console.log('Payment failed', failure)
          }
        />
      </TokenizationForm>
    </PayrailsProvider>
  );
}

How to Add Apple Pay

Apple Pay renders a native button on iOS and returns null on Android.

Prerequisites: Apple Pay must be configured in your Apple Developer account, and the device must have at least one card added.

import { ApplePay, useApplePayAvailable } from '@payrails/react-native-sdk';

const isAvailable = useApplePayAvailable();

{isAvailable && (
  <ApplePay
    buttonType="buy"
    buttonStyle="black"
    height={48}
    cornerRadius={8}
    onAuthorizeSuccess={() => console.log('Apple Pay succeeded')}
    onAuthorizeFailure={(failure) => console.log('Apple Pay failed', failure)}
    onAuthorizeCancel={() => console.log('User cancelled Apple Pay')}
  />
)}

How to Add Google Pay

Google Pay renders a native button on Android and returns null on iOS.

import { GooglePay, useGooglePayAvailable } from '@payrails/react-native-sdk';

const isAvailable = useGooglePayAvailable();

{isAvailable && (
  <GooglePay
    merchantInfo={{ merchantId: 'your-merchant-id', merchantName: 'Your Store' }}
    buttonType="pay"
    onAuthorizeSuccess={() => console.log('Google Pay succeeded')}
    onAuthorizeFailure={(failure) => console.log('Google Pay failed', failure)}
    onAuthorizeCancel={() => console.log('User cancelled Google Pay')}
  />
)}

How to Add PayPal

import { PayPal } from '@payrails/react-native-sdk';

<PayPal
  storeInstrument={false}
  style={{ height: 45 }}
  onAuthorizeSuccess={() => console.log('PayPal payment succeeded')}
  onAuthorizeFailure={(failure) => console.log('PayPal payment failed', failure)}
  onAuthorizeCancel={() => console.log('User cancelled PayPal')}
  onSessionExpired={async () => {
    const newConfig = await refreshSession();
    return { data: newConfig.data, version: newConfig.version };
  }}
/>

How to Pay with a Stored PayPal Account

import { useStoredPayPalInstruments, PayPal } from '@payrails/react-native-sdk';

const storedPayPalAccounts = useStoredPayPalInstruments();

<PayPal
  paymentInstrumentId={storedPayPalAccounts[0].id}
  onAuthorizeSuccess={() => console.log('Stored PayPal payment succeeded')}
  onAuthorizeFailure={(failure) => console.log('Failed', failure)}
/>

How to Add Generic Redirect (iDeal, pix, yape, etc.)

import { GenericRedirect, RedirectModes } from '@payrails/react-native-sdk';

<GenericRedirect
  paymentMethodCode="iDeal"
  redirectMode={RedirectModes.customTab}
  translations={{ label: 'Pay with iDEAL', loading: 'Redirecting...' }}
  styles={{
    base: { backgroundColor: '#CC0066', height: 48, borderRadius: 8 },
    loading: { opacity: 0.7 },
    pressed: { backgroundColor: '#AA0055' },
    disabled: { backgroundColor: '#ccc' },
  }}
  textStyles={{
    base: { color: '#FFFFFF', fontWeight: '600' },
    loading: { color: '#eee' },
    pressed: { color: '#fff' },
    disabled: { color: '#999' },
  }}
  onAuthorizeSuccess={() => console.log('iDEAL payment succeeded')}
  onAuthorizeFailure={(failure) => console.log('Failed', failure)}
  onAuthorizeCancel={() => console.log('User cancelled')}
  onSessionExpired={async () => {
    const newConfig = await refreshSession();
    return { data: newConfig.data, version: newConfig.version };
  }}
/>

How to Add Lean (Bank Transfer — UAE)

Prerequisites

Lean requires the peer dependency lean-react-native with version 4.2.0. Earlier versions may not be compatible.
Also install react-native-webview if it is not already installed in your project.

yarn add [email protected] react-native-webview
// OR
npm install [email protected] react-native-webview

The button label is fixed to "Pay by bank with Al Tareq." and cannot be overridden.

import { Lean } from '@payrails/react-native-sdk';

<Lean
  translations={{ loading: 'Processing...' }}
  styles={{
    base: { backgroundColor: '#00B67A', height: 48, borderRadius: 8 },
    loading: { opacity: 0.7 },
    disabled: { backgroundColor: '#ccc' },
  }}
  textStyles={{
    base: { color: '#FFFFFF', fontSize: 16, fontWeight: '600' },
    loading: { color: '#eee' },
    disabled: { color: '#999' },
  }}
  customization={{
    themeColor: '#0080ff',
    buttonTextColor: '#ffffff',
    buttonBorderRadius: '8',
    linkColor: '#0080ff',
    overlayColor: 'rgba(0, 0, 0, 0.8)',
  }}
  onAuthorizeSuccess={() => console.log('Success')}
  onAuthorizeFailure={(failure) => console.log('Failed', failure)}
  onAuthorizeCancel={() => console.log('Cancelled')}
  onSessionExpired={async () => {
    const newConfig = await refreshSession();
    return { data: newConfig.data, version: newConfig.version };
  }}
/>

For payment completion mode options (polling, background polling, return URLs), see Payment Completion Modes.