Features Documentation
Start typing to search…

Customizing Embedded Payment

Introduction

You can customize the look and feel of the Embedded Payment and utilize different features available for different payment methods. This gives you full control over how each payment method appears and behaves inside your embedded checkout flow.

General Customizations


ParameterTypeDescription
subscribedEventsArray of Strings of the event namesThe names of the events to which you want to subscribe
eventListenerFunctionA function that describes the action you want to take once an event is received to handle it accordingly
shouldHandlePaymentUrlBoolControls the payment flow for embedded payment methods

Event Types

Event NameDescriptionExample
VIEW_READYThis event is received once the embedded view is ready to be rendered on the page. You can hide it to display your loader until you get the event that the view is ready.{"name": "VIEW_READY", "id": 1, "paymentMethodName": "ALL", "data": {}}
CARD_IDENTIFIEDThis event is triggered once the user enters the first 10 digits of his card and the event includes the card information of the customer. This needs to be enabled for your account by the account manager.{"name": "CARD_IDENTIFIED", "id": 4, "paymentMethodName": "CARD", "data": {"cardBin": "512345", "cardBrand": "Mastercard", "issuer": "Test Bank", "issuerCountry": "KWT", "fundingMethod": "credit", "productName": "Mastercard Titanium"}}
PAYMENT_STARTEDThis event is triggered once the customer submits his card information or selects a specific payment method to make the payment.{"name": "PAYMENT_STARTED", "id": 2, "paymentMethodName": "CARD", "data": {}}
PAYMENT_COMPLETEDThis event is triggered when the customer completes the payment flow using the card. It will get triggered only in the case of shouldHandlePaymentUrl set to true.{"name": "PAYMENT_COMPLETED", "id": 3, "paymentMethodName": "CARD", "data": {}}
SESSION_STARTEDThis event is triggered when the user opens Apple Pay payment sheet after clicking on the button.
SESSION_CANCELEDThis event is triggered when the user closes Apple Pay payment sheet.
3DS_CHALLENGE_INITIATEDThis event is triggered when the OTP page is displayed to the user. It will get triggered only in the case of shouldHandlePaymentUrl set to true.{"name": "3DS_CHALLENGE_INITIATED", "id": 7, "paymentMethodName": "CARD", "data": {}}
OTP_REQUESTEDThis event will be triggered only in STC Pay when the customer receives the OTP.{"name": "OTP_REQUESTED", "id": 8, "paymentMethodName": "STC_PAY", "data": {"mobileNumber": "0548220713"}}

Customizations per Payment Method

You can customize each payment method individually, which will not apply these changes to the rest of the payment methods. You can customize each payment method using the same flow clarified in the sample code below.

var config = {
    sessionId: sessionId,
    callback: payment,
    containerId: "unified-session",
 		settings: {
        loader: { //This hides the loader that appears after the user submits his card information
            display: 'none'
        },
        card: {
            // Add your customization for card here
        },
        applePay: {
            // Add your customization for Apple Pay here
        },
        googlePay: {
            // Add your customization for Google Pay here
        },
        stcPay: {
            // Add your customization for STC Pay here
        }
    }
};

Card Customizations

ParameterTypeDescription
languageStringThis specifies the language in which Card text is displayed. This will override the one in the general config when the session created. (English)
styleObjectYou can manage the look and feel of the card from this object.
style.hideCardIconsBooleanYou can manage if you want to display the available card brands in the Card form or not. (False)
style.showCardholderNameBooleanEnables or disables the Cardholder Name input field in the card payment form. (True)
style.cardHeightStringThe height of the card form when the fields for card entry are displayed
style.tokenHeightStringThe height of the card form when the saved cards are displayed
style.inputObjectThis customizes the text entered by the customer, the form borders, and the placeholders in the card form.
style.textObjectThis customizes the text written on the card form for managing saving cards.
style.labelObjectThis customizes the labels that could be added over the fields of the card form.
style.errorObjectThis customizes the look of the fields when there is an error in the input of the customer.
style.buttonObjectYou can manage the button on which the customer clicks on after he fills in the card information. Please check below for more information
style.separatorObjectThis enables you to customize the separator displayed on the Embedded Payment before the Card form. Please check below for more information.

style.button:

Customize the look and feel of the button. There are two scenarios that you can rely on to enable your customer to click on a button to complete the payment after filling in the card information:

  1. Using MyFatoorah's default behavior: In this case, MyFatoorah manages all the functionalities of the button and returns to you the payment data in the callback function.
button: {
    useCustomButton: false,
    textContent: "Pay",
    fontSize: "16px",
    fontFamily: "Times",
    color: "white",
    backgroundColor: "black",
    height: "30px",
    borderRadius: "8px",
    width: "70%",
    margin: "0 auto",
    cursor: "pointer"
},
  1. Using your button with its functionalities
    In this case, you will be creating the button on your side and will manage its functionalities fully. It is mandatory to call the function myfatoorah.submitCardPayment() when the customer clicks on the payment button.
//Create the button on which the customer will click after entering the card information
//Define the function to call after the customer clicks on the button
<button onclick="customSubmit()"
        style="display: block; margin: 0 auto; width: 400px; height: 30px; cursor: pointer; background-color: #008CBA; border: none; color: white; font-size: 16px; border-radius: 8px;">
    Pay Now
</button>

// =================================
// Don't use MyFatoorah button
var button = {
    useCustomButton: true,
};

// =================================
// Define the function customSubmit to handle the payment process
function customSubmit() {
    // Here you can add the steps you want to do when the button is clicked.
    myfatoorah.submitCardPayment(); // This function is mandatory
};

myfatoorah.submitCardPayment()

This function can accept an object as an argument. The argument enables you to control the payment flow. The object can currently have two properties, currency and skipTokenSave.

var options = {
  currency: "USD",
  skipTokenSave: true
}

myfatoorah.submitCardPayment(options);

Validate card inputs

This function enables you to validate the input of the customer in the card form before calling MyFatoorah function to submit the card information. This also enables you to let your customers know which input field is incorrect by a customized error message on your end.

function customSubmit() {
    myfatoorah.validateCardInputs()
        .then(result => {
            console.log("success" + JSON.stringify(result)); // "Data fetched successfully!"
            myfatoorah.submitCardPayment(); //It is mandatory to call this function
        })
        .catch(error => {
            console.log("failed" + JSON.stringify(error)); // "Error fetching data."
        });
}

style.separator

From this object, you can customize the display of the separator before the Card to make it fit your website.

separator: {
    useCustomSeparator: false,
    textContent: "Pay with Card",
    fontSize: "14px",
    color: "#4daee0",
    fontFamily: "sans-serif",
    textSpacing: "5px",
    lineStyle: "dashed",
    lineColor: "black",
    lineThickness: "2px"
}

Card Sample Code

Below is a sample code clarifying the customizations of the card:

var config = {
    sessionId: sessionId,
    callback: payment,
  	containerId: "unified-session",
  	subscribedEvents: ['VIEW_READY', "CARD_IDENTIFIED", 'PAYMENT_STARTED', 'PAYMENT_COMPLETED', 'SESSION_STARTED', 'SESSION_CANCELED', '3DS_CHALLENGE_INITIATED', 'OTP_REQUESTED'],
		eventListener: eventHandler,
		shouldHandlePaymentUrl: true,
    settings: {
        card: {
						language: "ar",
            style: {
                showCardholderName: true,
        				hideCardIcons: true,
                cardHeight: "200px",
                tokenHeight: "230px",
                input: {
                    color: "black",
                    fontSize: "15px",
                    fontFamily: "courier",
                    inputHeight: "32px",
                    inputMargin: "3px",
                    borderColor: "black",
                    backgroundColor: "green",
                    borderWidth: "1px",
                    borderRadius: "30px",
                    outerRadius: "10px",
                    //boxShadow: "0 0 10px 5px purple, 0 0 15px 10px lightblue",
                  placeHolder: {
												color: "#DCEBFF",
                        holderName: "Name On Card",
                        cardNumber: "Number",
                        expiryDate: "MM/YY",
                        securityCode: "CVV",
                    }
                },
                text: {
                    saveCard: "Save card info for future payments",
                    addCard: "Use another Card!",
                    deleteAlert: {
                        title: "Delete",
                        message: "Are you sure?",
                        confirm: "YES",
                        cancel: "NO"
                    }
                },
                label: {
                    display: true,
                    color: "black",
                    fontSize: "13px",
                    fontWeight: "bold",
                    fontFamily: "Times",
                    text: {
                        holderName: "Card Holder Name",
                        cardNumber: "Card Number",
                        expiryDate: "Expiry Date",
                        securityCode: "Security Code",
                    },
                },
                error: {
                    borderColor: "red",
                    borderRadius: "8px",
                    //boxShadow: "0 0 10px 5px purple, 0 0 15px 10px lightblue",
                },
                button: {
                    textContent: "Pay",
                    fontSize: "16px",
                    fontFamily: "Times",
                    color: "white",
                    backgroundColor: "#4daee0",
                    height: "30px",
                    borderRadius: "8px",
                    width: "70%",
                    margin: "0 auto",
                    cursor: "pointer"
                },
                separator: {
                    useCustomSeparator: false,
                    textContent: "Enter your card",
                    fontSize: "20px",
                    color: "#4daee0",
                    fontFamily: "sans-serif",
                    textSpacing: "2px",
                    lineStyle: "dashed",
                    lineColor: "black",
                    lineThickness: "3px"
                }
            }
        }
    }
};

Apple Pay Customizations

ParameterTypeDescription
requiredBillingContactFieldsArrayThis will force the customer to enter the fields that you pass in the array in his Apple Pay wallet to be able to proceed with the payment. The information that he enters is then returned to you in the callback function
requiredShippingContactFieldsArrayThis will force the customer to enter the fields that you pass in the array in his Apple Pay wallet to be able to proceed with the payment. The information that he enters is then returned to you in the callback function
languageStringThis specifies the language in which Apple Pay text is displayed. This will override the one in the general config when the session created.
styleObjectYou can manage the look and feel of the Apple Pay button from here.

requiredShippingContactFields

If you're using this field, your customer cannot pay via Apple Pay unless he has entered his Shipping Information. You can retrieve the shipping information that the customer has in his Apple Pay wallet from the shippingContact object in the response of the callback function.

requiredShippingContactFields: ["postalAddress", "name", "phone", "email"],//You can remove what you don't need
"shippingContact": {
        "addressLines": ["ElIkhlas", "13"],
        "administrativeArea": "",
        "country": "Saudi Arabia",
        "countryCode": "SA",
        "emailAddress": "[email protected]",
        "familyName": "MyFatoorah",
        "givenName": "Tech",
        "locality": "Haram",
        "phoneNumber": "00201111111111",
        "phoneticFamilyName": "",
        "phoneticGivenName": "",
        "postalCode": "33651",
        "subAdministrativeArea": "",
        "subLocality": "Mariotia"
    }

requiredBillingContactFields

If you're using this field, your customer cannot pay via Apple Pay unless he has entered his Billing Information. You can retrieve the billing information that the customer has in his Apple Pay wallet from the billingContact object in the response to the callback function

requiredBillingContactFields: ["postalAddress", "name", "phone"],//You can remove what you don't need
"billingContact": {
        "addressLines": ["ElIkhlas", "13"],
        "administrativeArea": "",
        "country": "Saudi Arabia",
        "countryCode": "SA",
        "familyName": "MyFatoorah",
        "givenName": "Tech",
        "locality": "Riyadh",
        "phoneticFamilyName": "",
        "phoneticGivenName": "",
        "postalCode": "33651",
        "subAdministrativeArea": "",
        "subLocality": "As Sulimaniyah"
    }

style

This enables you to customize the display of the Apple Pay button.

style: {
    frameHeight: "40px",
    frameWidth: "100%",
    button: {
        height: "40px",
        type: "checkout", //["plain", "buy", "pay", "checkout", "continue", "book", "donate", "subscribe", "reload", "add", "topup", "order", "rent", "support", "contribute", "setup", "tip"]
        borderRadius: "20px",
    }
},

Apple Pay Sample Code

Below is a sample code clarifying the customizations of Apple Pay

var config = {
    sessionId: sessionId,
    callback: payment,
  	containerId: "unified-session",
		shouldHandlePaymentUrl: true,
    settings: {
        applePay: {
            //language: "ar",
            style: {
                frameHeight: "40px",
                frameWidth: "100%",
                button: {
                    height: "40px",
                    type: "buy", //["plain", "buy", "pay", "checkout", "continue", "book", "donate", "subscribe", "reload", "add", "topup", "order", "rent", "support", "contribute", "setup", "tip"]
                    borderRadius: "20px",
                }
            },
            requiredShippingContactFields: ["postalAddress", "name", "phone", "email"],
            requiredBillingContactFields: ["postalAddress", "name", "phone"],
        },
    }
};

Google Pay Customizations

ParameterTypeDescription
languageStringThis specifies the language in which Google Pay text is displayed. This will override the one in the general config when the session created.
styleObjectYou can manage the look and feel of the Google Pay button from here.

style

This enables you to customize the display of the Google Pay button

style: {
    frameHeight: "55px",
    frameWidth: "100%",
    button: {
        height: "40px",
        type: "pay", // Accepted texts: ["book", "buy", "checkout", "donate", "order", "pay", "plain", "subscribe"]
        borderRadius: "8px",
        color: "black" //["white", "black"]
    }
}

Google Pay Sample Code

Below is a sample code clarifying the customizations of Google Pay

var config = {
  sessionId: "KWT-e33b7416-8e3c-4d6e-a967-28c09d33e888", 
  callback: payment, 
  containerId: "unified-session",
  shouldHandlePaymentUrl: true, 
  settings: {
    googlePay: {
      //language: "ar",
      //callback: paymentGP,
      style: {
        frameHeight: "55px",
        frameWidth: "100%",
        button: {
          height: "40px",
          type: "pay", // Accepted texts: ["book", "buy", "checkout", "donate", "order", "pay", "plain", "subscribe"]
          borderRadius: "8px",
          color: "black",
        },
      },
    },
  },
};

STC Pay Customizations

ParameterTypeDescription
mobileNumberstringYou can add here a mobile number to be displayed by default and the customer can change it if he wants to use a different currency.
styleobjectThis enables you to customize the look and feel for STC Pay

mobileNumber:

The value of the mobile that you add here will be auto-filled in STC Pay by default. The customer can change or use the same mobile number that you have filled in here.

style

You can use these parameters to customize the view of STC Pay.

style: {
    frameHeight: "40px",
    frameWidth: "100%",
    input: {
        color: "#582490",
        fontSize: "14px",
        fontFamily: "'roboto', sans-serif",
        inputHeight: "40px",
        borderColor: "black",
        borderWidth: "2px",
        borderRadius: "9px",
        placeHolder: {
            mobileNumber: "05________",
            otpValue: "Enter OTP!"
        }
    },
    button: {
        borderRadius: "9px",
        height: "40px"
    }
}

STC Pay Sample Code

Below is a sample code clarifying the customizations of STC Pay

var config = {
  sessionId: sessionId,
  callback: payment, 
  containerId: "unified-session",
  shouldHandlePaymentUrl: true,
  settings: {
    stcPay: {
      mobileNumber: "0548220713",
      // language: "en",
      style: {
        frameHeight: "40px",
        frameWidth: "100%",
        input: {
          color: "#582490",
          fontSize: "14px",
          fontFamily: "'roboto', sans-serif",
          inputHeight: "40px",
          borderColor: "black",
          borderWidth: "2px",
          borderRadius: "9px",
          placeHolder: {
            mobileNumber: "05________",
            otpValue: "Enter OTP!",
          }
        },
        button: {
          borderRadius: "9px",
          height: "40px"
        }
      }
    }
  }
};

Updated about 2 hours ago