Payrails Elements are payment UI components you can assemble together to build a payment form.

Getting started

Although each Element (cards, Apple Pay, Google Pay, PayPal, etc) has its own signature, they follow a similar implementation.

Create the Element

const options = { /* object with Element configurations */ }
const myElement = payrailsClient.someElement(options);

Mount the Element to your DOM

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

HTML

<div id="element-container" />

JavaScript

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

You can use the unmount method to reset the Element to its initial state.

element.unmount();

Card Form Element

The cardForm element is a secure card tokenization form.

interface OnChange {
  isValid?: boolean,
  cardNetwork?: string,
  bin?: string
}

const element = payrails.cardForm({
  showCardHolderName: true,
  showStoreInstrumentCheckbox: true,
  showSingleExpiryDateField: true,
  styles: {
    inputFields: {
      all: {
        base: {
          '&:hover': {
            border: '1px solid black',
          },
        },
        focus: {
          border: '1px solid black',
        },
      },
    },
  },
  translations: {
    placeholders: {
      CARDHOLDER_NAME: 'Customized card holder',
      CARD_NUMBER: 'Custom card number',
      CVV: 'CODE',
      EXPIRATION_MONTH: 'MM',
      EXPIRATION_YEAR: 'YY',
    },
    labels: {
      saveCreditCard: 'Save card for future use',
    },
  },
  events: {
    onChange(e: OnChange) {
      console.log('card form change', e);
    },
    onFocus() {
      console.log('user set focus to input field');
    }
    onReady() {
      console.log('triggered when form is rendered and ready')
    }
  }
});

element.mount('#card-form-container');

The Card Form configuration is defined as shown below:

property	type	description
`showCardHolderName`	Boolean	To display the cardholder name input
`layout`	cardField[][]	to customize card form layout e.g. `[['CARDHOLDER_NAME'],['CARD_NUMBER'],['EXPIRATION_DATE', 'CVV']]`
`showSingleExpiryDateField`	Boolean	to only single expiry dat as `MM/YY`
`showStoreInstrumentCheckbox`	Boolean	To display a checkbox for customers to save their cards for later.
`styles`	Object	Styles that should be applied to the Element. Styles are specified with JSS.
`translations`	Object	Translations to localize the Element.
`events`	Object	The below events can be emitted by the Card Form element. For more details about events, see the SDK Events Glossary . `onChange` `onFocus` `onReady` `onSaveInstrumentCheckboxChanged`

Card form functions

Card form exposes the following functions

functions	description	params
`mount`	used to add the card form into the DOM	location: string
`unmount`	used to remove the card form from the DOM
`show`	Used to show the card form
`hide`	used to hide the card form. Pass `{reset : true}` if you want to reset the card form values on hide.	`{ reset: true \| false // defaults to false }`
`update`	used to update the styles and translations for the element	`{ styles: Object, translations: Object }`

Card List Element

The cardList element is a radio button list of the customer's saved instruments.

const element = payrails.cardList({
  styles: {
    border: "1px solid #eae8ee",
    padding: "10px 16px",
    borderRadius: "4px",
    color: "#1d1d1d",
  },
});

element.mount('#card-list-container');

The Card Form configuration is defined as shown below:

property	type	description
`styles`	Object	Styles that should be applied to the Element. Styles are specified with JSS.
`events`	Object	The below events can be emitted by the Card List element. For more details about events, see the SDK Events Glossary . `onCardChange`

property

type

description

styles

Object

Styles that should be applied to the Element. Styles are specified with JSS.

events

Object

The below events can be emitted by the Card List element. For more details about events, see the SDK Events Glossary .

onCardChange

Payment Button Element

The cardButton element is the card payment authorization button.

The cardButtoncan collect the content of the cardForm and cardList Elements. So, it would typically be used:

alone if there are no payment instruments to decide.
with a cardForm if the user will provide a new card.
with a cardList if the user will pick an existing instrument.
with both cardForm and cardList if the customer can provide a new card or use an existing instrument.

const element = payrails.paymentButton({
  label: 'Pay',
  disabledByDefault?: boolean;
  events: {
    onAuthorizeSuccess: () => {
      console.log('yay!');
    },
    onAuthorizeFailed: (e) => {
      console.log('nah :(', e);
    },
    onPaymentButtonClicked: (e) => {
      console.log('clicked', e);
      // If resolved to false authorization will not be triggered
      return Promise.resolve(true);
    },
    onPaymentSessionExpired() {
      console.log('session expired');
      // dropin has to be initialized with new workflow execution, contact your backend
    },
    onThreeDSecureChallenge() {
      console.log('3ds initiated');
      // triggered when 3DS challenge starts
    },
    onStateChanged(state: 'enabled' | 'disabled') {
      console.log(state);
      //triggered when button change the state from enabled to disabled
    }
  },
  styles: {
    base: {
      width: 'auto',
      border: '1px solid transparent',
      borderRadius: '12px',
      backgroundColor: '#0096b2',
      borderColor: 'transparent',
      color: '#fff',
      padding: '8px 24px',
      fontSize: '16px',
      minHeight: '48px',
    },
    disabled: {
      backgroundColor: '#d8dfe6',
      color: '#52667d',
    },
    hover: {
      backgroundColor: '#22a2be',
    },
  },
});

element.mount('#payment-button-container');

The Payment Button configuration is defined as shown below:

property	type	description
`label`	Object	Label for the form field.
`disabledByDefault`	boolean	set the default state for the payment button
`events`	Object	The below events can be emitted by the payment button element. For more details about events, see the SDK Events Glossary `onPaymentButtonClicked` `onThreeDSecureChallenge` `onPaymentSessionExpired` `onAuthorizeSuccess` `onAuthorizeFailed`
`styles`	Object	Styles that should be applied to the Element. Styles are specified with JSS.

`onAuthorizeFailed()` errors

callback receives the object describing the error that happened

enum AuthorizationFailureReasons {  
  VALIDATION_FAILED = 'VALIDATION_FAILED',  
  AUTHORIZATION_ERROR = 'AUTHORIZATION_ERROR',  
  AUTHENTICATION_ERROR = 'AUTHENTICATION_ERROR',  
  UNKNOWN_ERROR = 'UNKNOWN_ERROR',  
}

interface AuthorizationError {
  code: AuthorizationFauilureReasons
  message: string
  rawError?: any //if UNKNOWN_ERROR happens, raw error is available on the object
}

Failure reasons explanation

VALIDATION_FAILED: onPaymentButtonClicked wasn't resolved to true

AUTHORIZATION_ERROR: authorization failed, no technical reason. Details are in the message (different for 3DS)

AUTHENTICATION_ERROR: token used in SDK is invalid

UNKNOWN_ERROR: all other errors

`onPaymentButtonClicked()` event

Callback receives the object, containing:

{
  bin: '41111111' // optional, in case of card payment, returns the bin of the card
}

Payment Button functions

Payment Button exposes the following functions

functions	description	params
`update`	used to update the styles and translations for the element	`{ styles: Object, translations: Object }`

Google Pay Element

The googlePayButton element is an authorization button for Google Pay.

const element = payrails.googlePayButton({
  environment?: 'TEST' | 'PRODUCTION';
  showStoreInstrumentCheckbox?: boolean,
  merchantInfo?: {
    merchantId: string;
    merchantName?: string;
  };
  styles?: {
    buttonColor: google.payments.api.ButtonColor,
    buttonType: google.payments.api.ButtonType,
    buttonSizeMode: google.payments.api.ButtonSizeMode,
    buttonLocale: string,
    storeInstrumentCheckbox: {
      color: string,
      fontWeight: string,
    },
  },
  translations?: {
    labels: {
      storeInstrument: string,
    },
  },
  events: {
    onAuthorizeSuccess: () => {
      console.log('yay!');
    },
    onAuthorizeFailed: () => {
      console.log('nah :(');
    },
    onPaymentButtonClicked: async() => {
      console.log('clicked');
      // If resolved to false authorization will not be triggered
      return Promise.resolve(true);
    },
    onPaymentSessionExpired() {
      console.log('session expired');
      // dropin has to be initialized with new workflow execution, contact your backend
    },
  }
});

element.mount('#google-pay-button-container');

The Google Pay button configuration is defined as shown below:

property	type	description
`events`	Object	The below events can be emitted by the Google Pay element. For more details about events, see the SDK Events Glossary . `onPaymentButtonClicked` `onThreeDSecureChallenge` `onPaymentSessionExpired` `onAuthorizeSuccess` `onAuthorizeFailed` `onGooglePayAvailable`
`merchantInfo`	Object	`merchantId: string;` merchantId, not needed when in TEST `merchantName?: string;` merchant name displayed on payment sheet

property

type

description

events

Object

The below events can be emitted by the Google Pay element. For more details about events, see the SDK Events Glossary .

onPaymentButtonClicked
onThreeDSecureChallenge
onPaymentSessionExpired
onAuthorizeSuccess
onAuthorizeFailed
onGooglePayAvailable

merchantInfo

Object

merchantId: string; merchantId, not needed when in TEST
merchantName?: string; merchant name displayed on payment sheet

Google Pay availability

Payrails client provides the method to check if Google Pay is available in the current browser/client session. This is only necessary if one needs to know in advance if the payment method is supported. The GooglePayButton element otherwise has this logic encapsulated and will not render if the browser is not supported.c

const googlePay = isGooglePayAvailable(merchantInfo: google.payments.api.MerchantInfo)

property	type	description
`merchantInfo`	Object	`merchantId: string;` merchantId, not needed when in TEST - `merchantName?: string;` merchant name displayed on payment sheet

Apple Pay Element

The applePayButton element is an authorization button for Apple Pay.

const element = payrails.applePayButton({
  showStoreInstrumentCheckbox?: boolean,
  events: {
    onAuthorizeSuccess: () => {
      console.log('yay!');
    },
    onAuthorizeFailed: () => {
      console.log('nah :(');
    },
    onPaymentButtonClicked: async() => {
      console.log('clicked');
      // If resolved to false authorization will not be triggered
      return Promise.resolve(true);
    },
    onPaymentSessionExpired() {
      console.log('session expired');
      // dropin has to be initialized with new workflow execution, contact your backend
    },
    onApplePayAvailable() {
      console.log('Apple Pay ready');
      // event will fire when Apple Pay Button is initialized 
    },
    styles?: {
    	type?:
      	| 'plain'
      	| 'buy'
        | 'addMoney'
        | 'book'
        | 'checkout'
        | 'continue'
        | 'contribute'
        | 'donate'
        | 'inStore'
        | 'order'
        | 'reload'
        | 'rent'
        | 'setUp'
        | 'subscribe'
        | 'support'
        | 'tip'
        | 'topUp';
      style?: 'white' | 'whiteOutline' | 'black' | 'automatic';
    }
  }
});

element.mount('#apple-pay-button-container');

The Apple Pay button configuration is defined as shown below:

property	type	description
`events`	Object	The below events can be emitted by the Apple Pay element. For more details about events, see the SDK Events Glossary . `onPaymentButtonClicked` `onThreeDSecureChallenge` `onPaymentSessionExpired` `onAuthorizeSuccess` `onAuthorizeFailed` `onApplePayAvailable`

property

type

description

events

Object

The below events can be emitted by the Apple Pay element. For more details about events, see the SDK Events Glossary .

onPaymentButtonClicked
onThreeDSecureChallenge
onPaymentSessionExpired
onAuthorizeSuccess
onAuthorizeFailed
onApplePayAvailable

Apple Pay availability

Payrails client provides the method to check if Apple Pay is available in the current browser/client session. This is only necessary if one needs to know in advance if to render the element. The ApplePayButton element otherwise has this logic encapsulated and will not render if the browser is not supported.

const isAvailable = await payrails.isApplePayAvailable(); // returns boolean

PayPal Element

The paypalButton element is an authorization button for PayPal.

const element = payrails.paypalButton({
  showStoreInstrumentCheckbox: boolean; // default false
  alwaysStoreInstrument: boolean; // default false
  styles: {
    color: "'gold' | 'blue' | 'silver' | 'white' | 'black'",
    height: 30,
    label: "'paypal' | 'checkout' | 'buynow' | 'pay' | 'installment' | 'subscribe' | 'donate'",
    shape: "'rect' | 'pill'",
    tagline: "true | false",
    storeInstrumentCheckbox: Partial<CSSStyleDeclaration>;
  },
  events: {
    onAuthorizeSuccess: () => {
      console.log('yay!');
    },
    onAuthorizeFailed: () => {
      console.log('nah :(');
    },
    onPaymentButtonClicked: async() => {
      console.log('clicked');
      // If resolved to false authorization will not be triggered
      return Promise.resolve(true);
    },
    onPaymentSessionExpired() {
      console.log('session expired');
      // dropin has to be initialized with new workflow execution, contact your backend
    },
    onPaypalAvailable() {
      // called when paypal is available in the browser
    }
  },
  translations: {
    labels: {
      saveInstrument: string;
    };
  };
});

element.mount('#paypal-button-container');

The PayPal button configuration is defined as shown below:

property	type	description
`events`	Object	The below events can be emitted by the PayPal element. For more details about events, see the SDK Events Glossary . `onPaymentButtonClicked` `onThreeDSecureChallenge` `onPaymentSessionExpired` `onAuthorizeSuccess` `onAuthorizeFailed` `onPaypalAvailable`

property

type

description

events

Object

The below events can be emitted by the PayPal element. For more details about events, see the SDK Events Glossary .

onPaymentButtonClicked
onThreeDSecureChallenge
onPaymentSessionExpired
onAuthorizeSuccess
onAuthorizeFailed
onPaypalAvailable

PayPal FraudNet integration

Payrails SDK provides an easy way to integrate with PayPal FraudNet's solution.

/**
  | 'home-page'
  | 'search-result-page'
  | 'category-page'
  | 'product-detail-page'
  | 'cart-page'
  | 'inline-cart-page'
  | 'checkout-page';
**/
const page = 'checkout-page';

const fraudNet = payrails.fraudNet(page);
fraudNet.mount();

Generic Redirect Element

The genericRedirectButton element is an authorization button for Generic Redirect payment methods. The only method currently supported is Mercado Pago.

const element = payrails.genericRedirectButton({
  events: {
    onAuthorizeSuccess: () => {
      console.log('yay!');
    },
    onAuthorizeFailed: () => {
      console.log('nah :(');
    },
    onPaymentButtonClicked: async() => {
      console.log('clicked');
      // If resolved to false authorization will not be triggered
      return Promise.resolve(true);
    },
    onPaymentSessionExpired() {
      console.log('session expired');
      // dropin has to be initialized with new workflow execution, contact your backend
    }
  },
  translations: {
    // This value will be mapped to the payment button label
    label: "Pay using Payment Method";
  },
  styles: {
    background: "#474847",
    fontSize: "16px",
    color: "white",
    padding: "5px"
  }
});

element.mount('#genericRedirect-button-container');

The Generic Redirect button configuration is defined as shown below:

property	type	description
`events`	Object	The below events can be emitted by the Generic Redirect element. For more details about events, see the SDK Events Glossary . `onPaymentButtonClicked` `onThreeDSecureChallenge` `onPaymentSessionExpired` `onAuthorizeSuccess` `onAuthorizeFailed`
`translations`	Object	`label`, the display label will be mapped to the payment button.
`styles`	Object	Styling of the payment button. Follow the guidelines for styling buttons

property

type

description

events

Object

The below events can be emitted by the Generic Redirect element. For more details about events, see the SDK Events Glossary .

onPaymentButtonClicked
onThreeDSecureChallenge
onPaymentSessionExpired
onAuthorizeSuccess
onAuthorizeFailed

translations

Object

label, the display label will be mapped to the payment button.

styles

Object

Styling of the payment button. Follow the guidelines for styling buttons

Note: not all events are applicable for all generic redirect payment methods.

Generic Redirect functions

Generic Redirect exposes the following functions

functions	description	params
`update`	used to update the styles and translations for the element	`{ styles: Object, translations: Object }`

Getting started

Create the Element

Mount the Element to your DOM

HTML

JavaScript

Card Form Element

Card form functions

Card List Element

Payment Button Element

onAuthorizeFailed() errors

Failure reasons explanation

onPaymentButtonClicked() event

Payment Button functions

Google Pay Element

Google Pay availability

Apple Pay Element

Apple Pay availability

PayPal Element

PayPal FraudNet integration

Generic Redirect Element

Generic Redirect functions

`onAuthorizeFailed()` errors

`onPaymentButtonClicked()` event