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:

propertytypedescription
paymentMethodsConfigurationObjectPayment method configurations that are needed to customize the drop-in behavior. Read more here.
eventsObjectAttach your callables to the events emitted by the Drop-in. Read more here.
stylesObjectStyles that should be applied to the Drop-in. Read more here.
translationsObjectTranslations 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);
propertytypedescription
preselectFirstPaymentOptionbooleanAutomatically preselects the first payment option.
Defaults to false
cardsObjectcard 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
- alwaysStoreInstrumentto always store instruments
googlePayObjectgooglePay 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
}
applePayObjectapplePay element configurations:

- showStoredInstruments to show existing holder payment instruments
- showStoreInstrumentCheckbox to display a checkbox for customers to save their Apple Pay method for later
payPalObjectpayPal 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);
propertytypedescription
onAuthorizeSuccessCallableThis event is triggered when the Authorization is successful.
onAuthorizeFailedCallableThis 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.

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;
    };
  };
    mercadoPago: {
    label: 'dropin item label',
    button: {
      label: 'button label'
    }
  }

}

Handling 3DS

We have 2 modes for handling 3ds -

  1. 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.
  2. 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,
 });