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 a two-step process for starting drop-in for 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?: Object,
  events?: Object,
  styles?: Object,
  translations?: Object
};

const dropin = payrailsClient.dropin(configuration);

The Drop-in configuration is defined as shown below:

property	type	description
`paymentMethodsConfiguration`	Object	Payment method configurations that are needed 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
`preselectFirstPaymentOption`	boolean	Automatically preselects the first payment option. Defaults to `false`
`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 - `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 instrument 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 {
  // DropIn wrapper specific styles
  container?: {
  	style?: Partial<CSSStyleDeclaration>;
    className?: string;
  };
  // Basic styles for each drop-in component wrapper
  element?: {
    base?: Partial<CSSStyleDeclaration>;
    active?: Partial<CSSStyleDeclaration>;
    className?: string;
  };
  // 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>;
    storeInsrtumentCheckboxClassName?: string;
  };
  // 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>;
    storeInsrtumentCheckboxClassName?: string;
  };
  // 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>;
    storeInsrtumentCheckboxClassName?: string;
  };
  // Card form specific styles
  cardForm?: {
    wrapper?: Partial<CSSStyleDeclaration>;
    base?: Partial<CSSStyleDeclaration>;
    storeCardCheckbox?: Partial<CSSStyleDeclaration>;
    storeInstrumentCheckbox?: Partial<CSSStyleDeclaration>;
    storeInsrtumentCheckboxClassName?: string;
    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>;
  };
  mercadoPago: {
    base?: Partial<CSSStyleDeclaration>;
    active?: Partial<CSSStyleDeclaration>;
    className?: string;
  };
  authSuccess?: Partial<CSSStyleDeclaration>;
  authFailed?: Partial<CSSStyleDeclaration>;
}

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

Styling non sensitive elements

Drop-in config allows you to pass custom classnames for non-sensitive elements. Allowing to easily change the styling of the entire drop-in form to match your branding. You can customize:

Radio buttons
Store instrument checkboxes
Button styles
Custom font families
Custom spacing and animations

Additional information:

What is not customisable:

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

Show payment options logo

Payrails dropin also allows you to optionally show payment method logo alongside each payment method name.
You can pass the showPaymentMethodLogo as true for the payment methods you would want to show this.
By default this is false.

  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 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;
    pending?: string;
  };
  paypalButton?: {
    labels?: {
      saveInstrument?: string;
      label?: string;
    };
  };
    mercadoPago: {
    label: 'dropin item label',
    button: {
      label: 'button label'
    }
  }

}

Handling 3DS

We have 2 modes for handling 3ds -

Iframe based flow - In this flow the user sees the iframe as a popup to validate 3DS. We would recommend this flow to maximise conversion.
Redirection based flow - In this flow the user is redirected to the new page to validate 3DS. If you have very strong CSP settings which cannot be relaxed to acoomodate for 3DS, then we would recommend this flow.

The DropIn integration be default comes with the iframe based flow. In order to switch to redirection based flow, the payrails SDK needs to be initialized with redirectFor3DS to true.

Payrails.init(initResult.res, {
    redirectFor3DS: true,
 });