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,
  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: 'MO',
          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
`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.

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.

Payment Button Element

The cardButton element is the card payment authorization button.

The cardButton is able to 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 either provide a new card or use an existing instrument.

const element = payrails.paymentButton({
  label: 'Pay',
  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.
`events`	Object	Attach your callbacks to the events emitted by the Element: - `onAuthorizeSuccess() => void`, when the Authorization is successful. - `onAuthorizeFailed() => void`, when the Authorization failed.
`styles`	Object	Styles that should be applied to the Element. Styles are specified with JSS.

onAuthorizeFailed() errors

callback receives the object describing the error which 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
}

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	Attach your callbacks to the events emitted by the Element: - `onAuthorizeSuccess() => void`, when the Authorization is successful. - `onAuthorizeFailed() => void`, when the Authorization failed.
`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	Attach your callbacks to the events emitted by the Element: - `onAuthorizeSuccess() => void`, when the Authorization is successful. - `onAuthorizeFailed() => void`, when the Authorization failed.

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	Attach your callbacks to the events emitted by the Element: - `onAuthorizeSuccess() => void`, when the Authorization is successful. - `onAuthorizeFailed() => void`, when the Authorization failed.

PayPal FraudNet integration

Payrails SDK provides an easy way how to integrate with PayPal FraudNet 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	Attach your callbacks to the events emitted by the Element: - `onAuthorizeSuccess() => void`, when the Authorization is successful. - `onAuthorizeFailed() => void`, when the Authorization failed. - `onPaymentButtonClicked() => void`, when the payment button is clicked. - `onPaymentSessionExpired() => void`, when the payment session is expired.
`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.