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 the SDK using a <script> tag:
<script src=""></script>

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



Opens a modal containing an iframe with the Koalafi UI. Requires a valid orderId.

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

   .then((res) => {
      // Success
   .catch((err) => {
      // Error

// using async/await syntax within a custom function
const = yourCustomFunction = async () => {
	const koalafiResponse = await koalafiSdk.openModal(orderId)
        //handle error
  // use koalafiResponse here.

Resolved Promise

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

  • Finance application is approved (promise is not resolved in Shop First flow)
  • Finance is signed

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

// Application is approved 
   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