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
cardsBooleancard 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

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 as you wish:

const configuration = {
  styles: {
    cardForm: {
      border: "1px solid #eae8ee",
      padding: "10px 16px",
    },
    paymentButton: {
      borderRadius: "4px",
      color: "#1d1d1d",
    },
  },
};

const dropin = container.dropin(configuration);

Styles are specified with JSS.

Translations

For the Drop-in, translations are part of the dropin(options) signature, inside the translations object:

const configuration = {
  translations: {
    card: {
      placeholder: "Card Number",
      label: "card_number",
    },
  },
}

const dropin = container.dropin(configuration);

End-to-end example

Here's an end-to-end example of card collection with the Drop-in:

//Step 1
const dropin = payrailsClient.dropin({
  ...configuration,
  events: {
    onPaymentSuccess: () => {
      console.log('yay!');
    },
    onPaymentFailed: () => {
      console.log('nah :(');
    },
  },

});

// Step 2
dropin.mount("#dropin-container"); //assumes there is a div with id="#dropin-container" in the webpage