Payrails Drop-in 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 or APM redirect flows 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: frontend 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

Below is described a two-step process to start using Drop-in in your client.

Create the Drop-in component

First, create a Drop-in using the dropin(configuration) method of the Payrails client as shown below:

const configuration = {
  paymentMethodsConfiguration: {},
  events: {},
  styles: {},
  translations: {}
};

const dropin = payrailsClient.dropin(configuration);

The Drop-in configuration is defined as shown below:

property	type	description
`paymentMethodsConfiguration`	Object	Payment methods configurations to customize the Drop-in behavior. Read more here.
`events`	Object	Attach your callables to the events emitted by the Drop-in. Read more here.
`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.

Mount the Drop-in to the DOM

Now, when the mount(containerId) method of the Drop-in is called, the Drop-in will be inserted in the specified div. For instance, the call below will insert the Drop-in into the div with the id #dropin-container.

HTML

<div id="dropin-container" />

JavaScript

dropin.mount("#dropin-container");

You can use the unmount method to reset the Drop-in to its initial state.

dropin.unmount();

Payment methods behavior and configurations

const configuration = {
paymentMethodsConfiguration?: {
    cards?: {
      showCardHolderName?: boolean;
      showStoreInstrumentCheckbox?: boolean;
      showStoredInstruments?: boolean;
      showExistingCards?: boolean;
      alwaysStoreInstrument?: boolean;
    };
  };
};

const dropin = container.dropin(configuration);

property	type	description
`cards`	Object	card element configurations: - `showCardHolderName` to display the cardholder name input - `showStoreInstrumentCheckbox` to display a checkbox for customers to save their card for later - `showStoredInstruments` to show existing holder payment instruments - `showExistingCards` to show existing cards - `alwaysStoreInstrument`to always store instruments
googlePay	Object	googlePay element configurations: - `showStoredInstruments` to show existing holder payment instruments - `showStoreInstrumentCheckbox` to display a checkbox for customers to save their gpay for later - `merchantInfo?`: { `merchantId`: string; to set merchant id `merchantName?`: string; to set merchant name on payment sheet }
applePay	Object	applePay element configurations: - `showStoredInstruments` to show existing holder payment instruments - `showStoreInstrumentCheckbox` to display a checkbox for customers to save their Apple Pay method for later
payPal	Object	payPal element configurations: - `showStoredInstruments` to show existing holder payment instruments - `showStoreInstrumentCheckbox` to display a checkbox for customers to save their PayPal method for later

Event Listener

Attach your callables to the events emitted by the Drop-in:

const configuration = {
  events: {
    onAuthorizeSuccess: () => {
      console.log('yay!');
    },
    onAuthorizeFailed: () => {
      console.log('nah :(');
    },
  },
};

const dropin = container.dropin(configuration);

property	type	description
`onAuthorizeSuccess`	Callable	This event is triggered when the Authorization is successful.
`onAuthorizeFailed`	Callable	This event is triggered when the Authorization failed.

The handler function() => void is a callback function you provide, that will be called when the event is fired.

Styling

You can configure the style of the Drop-in and individual elements inside with this configuration object:

interface DropInStyles {
  // Basic styles for each drop-in component wrapper
  element?: {
    base?: Partial<CSSStyleDeclaration>;
    active?: Partial<CSSStyleDeclaration>;
  };
  // Google pay specific styles
  googlePayButton?: {
    buttonColor?: google.payments.api.ButtonColor;
    buttonType?: google.payments.api.ButtonType;
    buttonSizeMode?: google.payments.api.ButtonSizeMode;
    buttonLocale?: string;
    storeInstrumentCheckbox?: Partial<CSSStyleDeclaration>;
  };
  // PayPal specific styles
  paypalButton?: {
    color?: 'gold' | 'blue' | 'silver' | 'white' | 'black';
    height?: number;
    label?:
      | 'paypal'
      | 'checkout'
      | 'buynow'
      | 'pay'
      | 'installment'
      | 'subscribe'
      | 'donate';
    shape?: 'rect' | 'pill';
    tagline?: boolean;
    storeInstrumentCheckbox?: Partial<CSSStyleDeclaration>;
  };
  // Apple pay specific styles
  applePayButton?: {
    type?:
      | 'plain'
      | 'buy'
      | 'addMoney'
      | 'book'
      | 'checkout'
      | 'continue'
      | 'contribute'
      | 'donate'
      | 'inStore'
      | 'order'
      | 'reload'
      | 'rent'
      | 'setUp'
      | 'subscribe'
      | 'support'
      | 'tip'
      | 'topUp';
    style?: 'white' | 'whiteOutline' | 'black' | 'automatic';
    storeInstrumentCheckbox?: Partial<CSSStyleDeclaration>;
  };
  // Card form specific styles
  cardForm?: {
    wrapper?: Partial<CSSStyleDeclaration>;
    base?: Partial<CSSStyleDeclaration>;
    storeCardCheckbox?: Partial<CSSStyleDeclaration>;
    storeInstrumentCheckbox?: Partial<CSSStyleDeclaration>;
    errorTextStyles?: {
      base: Partial<CSSStyleDeclaration>;
    };
    inputFields?: {
      // Please see the ElementType enum for the available options
      [key in ElementType | 'all']?: {
        complete?: Partial<CSSStyleDeclaration>;
        empty?: Partial<CSSStyleDeclaration>;
        focus?: Partial<CSSStyleDeclaration>;
        invalid?: Partial<CSSStyleDeclaration>;
        cardIcon?: Partial<CSSStyleDeclaration>;
      };
    };
    labels?: {
      // Please see the ElementType enum for the available options
      [key in ElementType | 'all']?: Partial<CSSStyleDeclaration>;
    };
  };
  cardPaymentButton?: {
    base?: Partial<CSSStyleDeclaration>;
    disabled?: Partial<CSSStyleDeclaration>;
    loading?: Partial<CSSStyleDeclaration>;
    hover?: Partial<CSSStyleDeclaration>;
  };
  genericRedirect: {
  	base?: Partial<CSSStyleDeclaration>;
    active?: Partial<CSSStyleDeclaration>;
  };
}

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

Additional information:

What is not customisable:

Animations after successful/failed payments
Animation on Payment button
Radio buttons
If you would like to add some possibilities, please contact the Payrails team.

Translations

For the Drop-in, translations are part of the dropin(options) signature, inside the translations. here's the complete interface:

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

interface Translations {
  googlePayButton?: {
    labels?: {
      label?: string;
      storeInstrument?: string;
    };
  };
  cardPaymentButton?: {
    label: 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 | 'saveCreditCard']?: string;
    } & {
      storeInstrument?: string;
    };
  };
  paymentResult?: {
    success?: string;
    fail?: string;
  };
  paypalButton?: {
    labels?: {
      saveInstrument?: string;
      label?: string;
    };
  };
	genericRedirect?: {
		label?: string;
		button?: string;
	}
}