Payrails Drop-in for React Native is our pre-built UI solution for accepting payments on your application. Drop-in shows all payment methods as a list, in the same block.

Tokenizing new cards, adding new payment methods, and managing 3D-Secure usually don't require more development work than simply integrating our drop-in into your user journey.

How it works

From an implementation perspective, a Drop-in integration contains:

Server-side: a single API call that creates the payment session.
Client-side: react native component, which uses the payment session data to make the payment request and to handle any other actions like redirects or 3D Secure authentication.
Webhook server: receives notifications that inform you about the outcome of each payment.

Getting started

To get started first install '@payrails/react-native-sdk' package and after installation you need to import PayrailsDropin component.

Create the Drop-in component

To integrate Payrails Drop-in into your application, you need PayrailsDropin component First, initialize the payment context by making a call to /client/init endpoint, then use the received data to set up the component:

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

// initData  is response of your /client/init call 
// without initData drop-in component will not be rendered
<PayrailsDropin 
    config={initResponse}
    {...dropinProps}
/>

The Drop-in dropinProps is defined as shown below:

property	type	description
`config`	Object	It is `data` attribute of `/client/init`call, drop-in component will not be rendered without a valid config
`paymentMethodsConfiguration`	Object	Payment method configurations that are needed to customize the drop-in behavior. Read more here.
`events`	Object	Check the table below to see the events you can listen
`styles`	Object	Styles that should be applied to the Drop-in. Read more here.
`translations`	Object	Translations to localize the Drop-in. Read more here.

events:

property	type	description
`onRequestProgressChange`	Function	A callback fired when the payment processing state changes (starts/ends), useful for showing/hiding loading indicators in your UI.
`onAuthorizeStart`	Function	Must return true to proceed with payment authorization; use for any pre-payment validation checks.
`onAuthorizeSuccess`	Function	Called when the payment has been successfully processed and authorized.
`onAuthorizeFailure`	Function	Called when the payment authorization fails for any reason.
`onAuthorizeRequestStart`	Function	Called specifically for Apple Pay and Google Pay payments when the authorization request begins.
`onPaymentOptionSelected`	Function	Called when the user selects a payment method in the payment form.
`onBillingAddressChanged`	Function	Called when user changed country code or postal code (this function is called only if address selection is enabled)

Styling

You can configure the style of the Drop-in and individual elements passed in stylesprop

type DropinStyles = {
  container?: {
  	base?: ViewStyle;
  };

  element?: {
    neutral?: {
      container?: ViewStyle;
      radioOuter?: ViewStyle;
      label?: TextStyle;
      logo?: ImageStyle;
    };
    selected?: {
      container?: ViewStyle;
      radioOuter?: ViewStyle;
      radioInner?: ViewStyle;
      label?: TextStyle;
      logo?: ImageStyle;
    };
  };

  googlePayButton?: {
    type?: 'pay' | 'buy' | 'book' | 'checkout' | 'donate' | 'order' | 'subscribe' | 'mark';
    style?: ViewStyle
  };

  paypalButton?: {
    color?: 'gold' | 'blue' | 'silver' | 'white' | 'black';
    height?: number;
    label?:
      | 'paypal'
      | 'checkout'
      | 'buynow'
      | 'pay'
      | 'installment'
      | 'subscribe'
      | 'donate';
    shape?: 'rect' | 'pill';
    tagline?: boolean;
  };

  applePayButton?: {
    type?: 'plain' | 'buy' | 'setUp' | 'inStore' | 'donate' | 'checkout' | 'book' | 
           'subscribe' | 'reload' | 'addMoney' | 'topUp' | 'order' | 'rent' | 
           'support' | 'contribute' | 'tip' | 'continue';
    buttonStyle?: 'white' | 'whiteOutline' | 'black';
  };

  cardForm?: {
    inputFields?: InputStyles;
    errorTextStyles?: {
      base: TextStyle;
    };
    cardNumberInput?: InputStyles;
    expiryDateInput?: InputStyles;
    cvvInput?: InputStyles;
    cardholderNameInput?: InputStyles;
  };

  cardPaymentButton?: {
    base?: Record<string, string | number>;
    disabled?: Record<string, string | number>;
    text?: Record<string, string | number>;
  };
  
  storeInstrumentSwitch: {
    style?: ViewStyle;
    thumbColor?: string;
    trackColor?: {
      false?: string; // Color when switch is OFF
      true?: string; // Color when switch is ON
    };  
  }
  
  addressInput?: {
  	wrapper?: ViewStyle | TextStyle;
    countrySelector?: {
    	wrapper?: ViewStyle | TextStyle;
      element?: ViewStyle | TextStyle;
      label?: TextStyle;
      error?: ViewStyle | TextStyle;
    }
    postalCodeInput?: {
    	wrapper?: ViewStyle | TextStyle;
      element?: ViewStyle | TextStyle;
      label?: TextStyle;
      error?: ViewStyle | TextStyle;
    }
  }
};

Payment methods configuration

The PaymentMethodsConfiguration interface allows users to customize how payment options appear and behave in their application. Users can enable or disable features like displaying stored payment methods, showing logos, and adding checkboxes for saving new instruments. For card payments, additional settings such as showing the cardholder's name and existing saved cards are available. Additionally, the extended PaymentMethodsConfigurationWithInternal includes internal settings like toggling card form labels. This flexibility ensures a tailored and consistent payment experience across various methods like PayPal, Google Pay, Apple Pay.

Example of how to control rendering logos

  paymentMethodsConfiguration: {
    preselectFirstPaymentOption: true,
    cards: {
      showCardHolderName: true
      showExistingCards: true
      showPaymentMethodLogo: true,
    },
    payPal: {
      showPaymentMethodLogo: true,
    },
    googlePay: {
      showPaymentMethodLogo: false,
    },
    applePay: {
      showPaymentMethodLogo: false,
    },
    mercadoPago: { // hpp integration
      showPaymentMethodLogo: true,
    },
  },
}

Translations

For the Drop-in, translations are part of the drop-in component props. Here's the complete translationinterface:

export enum ElementType {
  CARD_NUMBER = 'CARD_NUMBER',
  CARDHOLDER_NAME = 'CARDHOLDER_NAME',
  CVV = 'CVV',
  EXPIRATION_MONTH = 'EXPIRATION_MONTH',
  EXPIRATION_YEAR = 'EXPIRATION_YEAR',
  EXPIRATION_DATE = 'EXPIRATION_DATE',
}

export interface Translations {
  googlePayButton?: {
    labels?: {
      storeInstrument?: string;
    };
  };
  cardPaymentButton?: {
    labels?: {
      neutral?: string;
      processing?: string;
    };
  };
  cardForm?: {
    placeholders?: {
      // please see the ElementType enum for the possible values of key
      [key in ElementType]?: string;
    };
    labels?: {
      // please see the ElementType enum for the possible values of key
      [key in ElementType]?: string;
    } & {
      label?: string;
      storeInstrument?: string;
    };
  };
  paymentResult?: {
    success?: string;
    fail?: string;
    pending?: string;
  };
  paypalButton?: {
    labels?: {
      storeInstrument?: string;
    };
  };
  applePayButton?: {
    labels?: {
      storeInstrument?: string;
    };
  };
}