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: '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
andcardList
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 callables 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({
styles: {
buttonColor: google.payments.api.ButtonColor,
buttonType: google.payments.api.ButtonType,
buttonSizeMode: google.payments.api.ButtonSizeMode,
buttonLocale: 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 callables to the events emitted by the Element: - onAuthorizeSuccess() => void , when the Authorization is successful.- onAuthorizeFailed() => void , when the Authorization failed. |
Apple Pay Element
The applePayButton
element is an authorization button for Apple Pay.
const element = payrails.applePayButton({
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
},
}
});
element.mount('#apple-pay-button-container');
The Apple Pay button configuration is defined as shown below:
property | type | description |
---|---|---|
events | Object | Attach your callables 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 callables 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();
Updated 2 months ago