JavaScript SDK

Use our JavaScript SDK to use the Koalafi UI in your checkout flow.

📘

Make sure to review Key Concepts and Getting Started first.

Import

Import the SDK using a <script> tag:
<script src="https://ecomm-sdk.sandbox.koalafi.com/koalafiSdk.js"></script>

After the script tag, you may now access the SDK by calling koalafiSdk.<function name>

Functions

openModal

Opens a modal containing an iframe with the Koalafi UI. Requires a valid orderId and publicDealerId. If you are a hybrid integration, you will also need to pass the hybridToken parameter, found in the x-hybrid-token header of the response to the apply mutation or customer query.

openModal returns a promise. Depending on the outcome of the modal UI session, the promise will be resolved or rejected. The promise will be resolved when the UI session was successful and rejected if there was an error during the session, or if the user exited out of the modal prematurely.

Sample Code Snippets

koalafiSdk.openModal(
            {
            orderId: orderId,
            pdi: publicDealerId,
            // hybridToken: hybridToken if you are doing hybrid integration 
          })
   .then((res) => {
      // Success
   })
   .catch((err) => {
      // Error
   });

// using async/await syntax within a custom function
const = yourCustomFunction = async () => {
	const koalafiResponse = await koalafiSdk.openModal(
            {
            orderId: orderId,
            pdi: publicDealerId,
          })
     .catch((err)=>{
        //handle error
     });
  // use koalafiResponse here.
};
yourCustomFunction();

Resolved Promise

A "successful" UI session occurs in the following situations:

• Finance application is approved (only resolved when there are no items on the Koalafi order)
• Finance is signed

The resolved promise will be in the following formats (with sample values):

// Application is approved 
{
   orderId:"2c5975d7-32e5-4072-8abf-8d17dade322a",
   approvalStatus: "preApproved",
   approvalAmount: "2500",
}

// Financing is signed successfully
{
   orderId: "2c5975d7-32e5-4072-8abf-8d17dade322a"
}

Rejected Promise

The following are reasons why the promise will be rejected:

• Finance application was declined
• Customer is ineligible to apply
• Customer's total cart value was outside the acceptable range ($300-$10000)
• There was a general error during the flow
• Customer has closed the modal from within the application with no error
• Customer has closed the modal with the X button

The rejected promise will be in the following format:

{
   orderId: "2c5975d7-32e5-4072-8abf-8d17dade322a",
   reasonCode: 2,
   reason: 'hardDecline',
}

The reasonCode property will be one of the following values:

genericError = 1
hardDecline = 2
ineligible = 3
cartAmtNotMet = 4
noCartItems = 5
cartAmtTooHigh = 6
generalCloseModal = 7
nonLeaseableTooHigh = 8
genericCartValidationErr = 9

Modal Event Listeners

To determine when a user closes our modal, we ask that you have an event listener listen for the 'closeModal' event. While the promise will be resolved immediately after the customer has signed their lease docs, the customer is shown one final screen informing them they have completed their Koalafi lease. An example event listener is shown below.

1. Listen for the ‘closeModal’ event which will be called when the user closes the modal
2. Upon receiving the closeModal event, query the order to ensure the application is in the proper state

🚧

Note!

This close modal event will be called both when the lease has been completed as well as if the user prematurely closes the modal. To determine the status of the lease, we suggest querying order after receiving an event.

Example Event Listener

window.addEventListener(
  'closeModal',
  function (event) {
    console.log(event.detail)
  },
  false
);