Elements
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: '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 |
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 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 |
Payment Button Element
The cardButton
element is the card payment authorization button.
The cardButton
can 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
andcardList
if the customer can 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 | 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
onAuthorizeFailed()
errorscallback 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
onPaymentButtonClicked()
eventCallback 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 | 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 |
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 |
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 |
Note: not all events are applicable for all generic redirect payment methods.
Updated about 1 month ago