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:

propertytypedescription
paymentMethodsConfigurationObjectPayment methods configurations 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
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
- showExistingCards to show existing cards
- alwaysStoreInstrumentto always store instruments
googlePayObjectgooglePay 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
}
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>;
  };
  genericRedirect: {
  	base?: Partial<CSSStyleDeclaration>;
    active?: Partial<CSSStyleDeclaration>;
    className?: string;
  };
}

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;
    };
  };
  genericRedirect?: {
    label?: string;
    button?: string;
  }
}