API References

Drop-in API Reference

PayrailsDropin

Props

PropTypeRequiredDescription
configInitDataYesOptional init payload { data: string; version: string} from the /client/init response.
paymentMethodsConfigurationPaymentMethodsConfigurationNoPer-method display and behaviour options.
eventsDropinEventsYesPayment lifecycle callbacks.
stylesDropinStylesNoVisual styling for the Drop-in container and all child elements.
translationsTranslationsNoLocalised labels for all Drop-in UI strings.

Events

PropertyTypeDescription
onRequestProgressChange(inProgress: boolean) => voidFired when payment processing starts or ends.
onAuthorizeStart() => booleanCalled before authorization begins. Return true to proceed.
onAuthorizeSuccess(result: AuthorizeResult) => voidCalled when the payment is successfully authorized.
onAuthorizeFailure(failure: AuthorizeFailure) => voidCalled when authorization fails.
onAuthorizeRequestStart() => voidCalled when the authorization request begins for Apple Pay and Google Pay.
onPaymentOptionSelected(option: PaymentOption) => voidCalled when the user selects a payment method.
onBillingAddressChanged(address: BillingAddress) => voidCalled when the user changes country code or postal code. Only fires when address selection is enabled.

Styling

Pass a DropinStyles object to the styles prop.

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;
    };
  };

  leanButton?: {
    styles?: {
      base?: ViewStyle;
      loading?: ViewStyle;
      disabled?: ViewStyle;
    };
    textStyles?: {
      base?: TextStyle;
      loading?: TextStyle;
      disabled?: TextStyle;
    };
    customization?: {
      themeColor?: string;
      buttonTextColor?: string;
      buttonBorderRadius?: string;
      linkColor?: string;
      overlayColor?: string;
    };
  };

  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' | 'white-outline' | '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;
      true?: string;
    };
  };

  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

Controls how individual payment methods appear and behave within the Drop-in.

paymentMethodsConfiguration: {
  preselectFirstPaymentOption?: boolean;
  cards?: {
    showCardHolderName?: boolean;
    showExistingCards?: boolean;
    showPaymentMethodLogo?: boolean;
  };
  payPal?: {
    showPaymentMethodLogo?: boolean;
  };
  googlePay?: {
    showPaymentMethodLogo?: boolean;
  };
  applePay?: {
    showPaymentMethodLogo?: boolean;
  };
  mercadoPago?: {
    showPaymentMethodLogo?: boolean;
  };
}

Translations

All UI strings are localised through the translations prop.

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?: {
      [key in ElementType]?: string;
    };
    labels?: {
      [key in ElementType]?: string;
    } & {
      label?: string;
      storeInstrument?: string;
    };
  };
  leanButton?: {
    labels?: {
      loading?: string;
      // Note: the button label is fixed to "Pay by bank with Al Tareq." and cannot be overridden.
    };
  };
  paymentResult?: {
    success?: string;
    fail?: string;
    pending?: string;
  };
  paypalButton?: {
    labels?: {
      storeInstrument?: string;
    };
  };
  applePayButton?: {
    labels?: {
      storeInstrument?: string;
    };
  };
}

Elements API Reference

All Elements must be rendered inside a PayrailsProvider. For usage examples, see How to Use Elements.


PayWithCardButton

Renders a payment button for a stored card instrument.

PropTypeRequiredDescription
instrumentStoredCardInstrumentYesThe stored card instrument to charge
titlestringNoCustom button label
onAuthorizeSuccess() => voidNoCalled when payment is authorized
onAuthorizeFailure(failure: AuthorizeFailure) => voidNoCalled when authorization fails
onRequestProgressChange(inProgress: boolean) => voidNoCalled when request state changes

The button displays the card network icon and masked card number automatically. It is disabled while a payment request is in progress.

Hooks

HookReturnsDescription
useStoredCardInstrumentsStoredCardInstrument[]Retrieves saved card instruments for the current session

PayWithNewCardButton

Renders the submit button for a new card payment. Must be placed inside a TokenizationForm.

PropTypeRequiredDefaultDescription
titlestringNo"Confirm payment"Button label
shouldSaveCardbooleanNoWhether to store the card for future use
dropinStylesCustomStylingPropsNoCustom button styles
translationsTranslationsNoLocalised labels
isAddressEnabledbooleanNoEnables billing address validation
onAuthorizeSuccess() => voidNoCalled when payment is authorized
onAuthorizeFailure(failure: AuthorizeFailure) => voidNoCalled when authorization fails

The button is automatically disabled until all card fields pass validation.

Related hooks

HookReturnsDescription
useBinLookupBinLookupResultIdentifies card network from BIN as user types
useTokenizeTokenizeFunctionTokenizes card data without executing a payment

ApplePay

Renders the native Apple Pay button on iOS. Returns null on Android and when Apple Pay is unavailable.

PropTypeRequiredDescription
buttonTypeButtonTypeNoButton label variant: "plain", "buy", "setUp", "inStore", "donate", "checkout", "book", "subscribe", "reload", "addMoney", "topUp", "order", "rent", "support", "contribute", "tip", "continue"
buttonStyleButtonStyleNoButton appearance: "white", "whiteOutline", "black"
widthnumberNoButton width in pixels
heightnumberNoButton height in pixels
cornerRadiusnumberNoButton corner radius
storeInstrumentbooleanNoWhether to save the instrument for future use
labelstringNoPayment label shown in the Apple Pay sheet
onAuthorizeSuccess() => voidNoCalled when Apple Pay payment is authorized
onAuthorizeFailure(failure: AuthorizeFailure) => voidNoCalled when authorization fails
onAuthorizeCancel() => voidNoCalled when the user cancels the Apple Pay sheet

Hooks

HookReturnsDescription
useApplePayAvailablebooleantrue when Apple Pay is configured and available on the device

GooglePay

Renders the native Google Pay button on Android. Returns null on iOS and when Google Pay is unavailable.

PropTypeRequiredDescription
merchantInfoMerchantInfoYes{ merchantId: string, merchantName?: string, merchantOrigin?: string }
buttonTypeButtonTypeNoButton label variant: "pay", "buy", "book", "checkout", "donate", "order", "subscribe", "mark"
storeInstrumentbooleanNoWhether to save the instrument for future use
styleRecord<string, any>NoCustom button styles
onAuthorizeSuccess() => voidNoCalled when Google Pay payment is authorized
onAuthorizeFailure(failure: AuthorizeFailure) => voidNoCalled when authorization fails
onAuthorizeCancel() => voidNoCalled when the user cancels Google Pay

Hooks

HookReturnsDescription
useGooglePayAvailablebooleantrue when Google Pay is available on the device

PayPal

Renders a PayPal payment button. Works on both iOS and Android.

PropTypeRequiredDescription
storeInstrumentbooleanNoWhether to save the PayPal account for future use
paymentInstrumentIdstringNoStored PayPal instrument ID; charges the saved account directly without opening a redirect
stylePayPalButtonStyleConfigNoButton style. Supports height (number, 30–55px)
onAuthorizeSuccess() => voidNoCalled when PayPal payment is authorized
onAuthorizeFailure(failure: AuthorizeFailure) => voidNoCalled when authorization fails
onAuthorizeCancel() => voidNoCalled when the user cancels the PayPal flow
onSessionExpired() => Promise<{ data: string; version: string } | void>NoCalled when the session expires; return a refreshed config

Hooks

HookReturnsDescription
useStoredPayPalInstrumentsStoredPayPalInstrument[]Retrieves saved PayPal accounts for the current session

GenericRedirect

Renders a redirect-based payment button for methods such as iDEAL, Pix, Yape, MercadoPago, and others.

PropTypeRequiredDescription
paymentMethodCodestringYesPayment method identifier: "ideal", "pix", "yape", "mercadopago", "bankaccount", "revolutpay"
redirectModeRedirectModesNoHow to open the redirect URL. Default: RedirectModes.customTab. Options: customTab, defaultBrowser
translations{ label?: string; loading?: string }NoButton text overrides
styles{ base?, loading?, pressed?, disabled? }NoViewStyle per button state
textStyles{ base?, loading?, pressed?, disabled? }NoTextStyle per text state
onAuthorizeSuccess() => voidNoCalled when payment is authorized
onAuthorizeFailure(failure: AuthorizeFailure) => voidNoCalled when authorization fails
onAuthorizeCancel() => voidNoCalled when the user cancels
onSessionExpired() => Promise<{ data: string; version: string } | void>NoCalled when the session expires; return a refreshed config

paymentMethodCode must match the payment method code from your configuration exactly, including case.

RedirectModes

ValueBehavior
RedirectModes.customTabOpens in Chrome Custom Tab (Android) / SFSafariViewController (iOS). Recommended. Falls back to default browser if custom tabs are unavailable.
RedirectModes.defaultBrowserOpens the system browser. The user must manually return to the app. The SDK detects app foregrounding to resume.

Lean

Renders a bank transfer payment button for the UAE, powered by the Lean SDK checkout dialog.

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 via translations.

PropTypeRequiredDescription
translationsLeanTranslationsNo{ loading?: string } — only the loading text is configurable
stylesLeanStylesNoViewStyle per button state: base, loading, disabled
textStylesLeanTextStylesNoTextStyle per text state: base, loading, disabled
customizationLeanCustomizationNoLean checkout dialog theming (see below)
onAuthorizeSuccess() => voidNoCalled when the bank transfer is authorized
onAuthorizeFailure(failure: AuthorizeFailure) => voidNoCalled when authorization fails
onAuthorizeCancel() => voidNoCalled when the user dismisses the Lean dialog
onSessionExpired() => Promise<{ data: string; version: string } | void>NoCalled when the session expires; return a refreshed config

LeanCustomization

PropertyTypeDescription
themeColorstringPrimary color for the Lean checkout dialog UI
buttonTextColorstringText color on dialog buttons
buttonBorderRadiusstringBorder radius of dialog buttons (e.g. "8")
linkColorstringColor of links inside the dialog
overlayColorstringOverlay backdrop color

For payment completion options, see Payment Completion Modes.


Event Callbacks

All Elements share the same callback contract. See the React Native event glossary for full type definitions.