Documentation
Start typing to search…

Lease Approval & Checkout (B&M)

At this point your customer has been approved for a brick and mortar lease. You can finish the lease financing process by either using a combination of our APIs and the merchant portal or entirely using our APIs. This page walks through the remaining steps for both options. To complete the steps on this page, you should still have the Koalafi orderId for the app in progress as well as the lease applicationId returned from the apply mutation.

🚧

Order is important!

The order of calls is important in this step! Please don't call the following endpoint asynchronously as they are dependent on each other.

Checkout with non-prequal Application

These are the steps for checking out via API, however, you can also complete checkout through our Koalafi Dealer Portal.

1. Update Debit Info

The lease approval returned from apply is actually considered a pre-approval and in order to continue on with Koalafi financing, we need to run an authorization for an initial payment on their debit card. We will only charge the card after the customer has signed the lease agreement; if they choose not to sign the lease, the authorization will be removed.

We do not store the card details that were sent to us on apply so we will need the debitDetails to be resent along with the lease applicationId returned from apply, in an input that looks like:

{
   "input":{
      "debitDetails":{
         "cardholderFirstName":"Wally",
         "cardholderLastName":"Koala",
         "cardNumber":"4000056655665556",
         "expirationDate":"2023-05"
      },
      "applicationId": 25125
   }
}

The UpdateDebitInfoResponse object only returns updateDebitInfo errors so the mutation you send will be short but should listen for information on all possible errors.

mutation updateDebitInfo($input: UpdateDebitInfoInput!) {
  updateDebitInfo(input: $input) {
    updateDebitInfoErrors {
      __typename
      ... on FatalError {
        message
      }
      ... on HardDecline {
        message
      }
      ... on SoftDecline {
        message
        extensions {
          displayText
        }
      }
    }
  }
}

Most of the time when you encounter an error, you will need to have the customer review their debit data and then retry the mutation. Our Handling Common Errors page explains what the different error type represents as well as the specific messaging and steps to take to resolve the errors. These errors must be resolved before moving on to Step 4.

Once this endpoint has been called and Initial Payment has been authorized, the application will now officially in the approved status.

2. Update Order Items

If a customer has had the chance to update their cart since their initial lease approval you need to call updateOrderItems before checkout to sync the Koalafi cart with the customer’s. Please note it is not necessary to call updateOrderItems after every cart change as we only need the final cart they have at checkout. For example, our e-commerce plugins call updateOrderItems before they open our modal on the checkout page. This ensures that the customer's cart and the Koalafi cart are always in sync.

An example of mutation for updateOrderItems looks something like:

mutation updateOrderItems($input: UpdateOrderItemsInput! ) {
  updateOrderItems(input: $input) {
    order {
      id
      details{
        items{
          price
        }
      }
    }
    orderErrors{
      __typename
      ... on CartValidation {
        message
        extensions {
          validationErrType
          approvalType
          approvedAmount
        }
      }
      ... on BadRequest{
        message
      }
      ... on CartMinNotMet{
        message
      }
    }  
  } 
}

For this response, the most important thing to check is orderErrors as any error needs to be addressed before the customer can continue with their application. We have broken down the different possible errors for this mutation and recommended resolution in our Handling Common Errors page.

Discount Codes / Coupons

Some retailers will offer discount codes or coupons at checkout. In order to make sure the Koalafi contract amount matches the discounted price from the merchant, you will need to apply the coupon/discount to the items' prices before calling updateOrderItems. Before calling this mutation, you need to make sure that the cart total you are sending matches the discounted cart total on the site and that each item's price is formatted to have 2 decimal places. If their cart contains multiple items, the price you send for each item should match what's shown on the e-comm site.

Non Leasable Items

Specifying whether a product is leasable is required when offering a lease-to-own financing option with Koalafi. Non-leasable products generally include weapons and non-physical goods such as gift cards, service fees, warranties or installation fees. It is important that Koalafi knows when a customer is purchasing a non-leaseable item as they can only make up a 20% of a customer's total purchase.

You can use the boolean field isLeaseable on the updateOrderItems input to indicate that an item is non-leaseable. By default, we assume all products are leaseable so this isLeaseable: false must be sent to let our system know otherwise.

Our e-commerce platform integrations allow merchants to tag all non-leaseable items in their inventory as such so that it's easy to send to Koalafi when a customer selects that item. We suggest a similar solution to all our direct API integration partners.

❗️

Cart Changes

If the customer changes their cart at all prior to submitting the purchase in the merchant's system, then you’ll need to call updateOrderItems again. This is important because it ensures that lease agreement the customer signs matches the price of the purchases they’re making on your site.

4. Customer Reviews and Acknowledges Contract Summary

Once a customer's app has reached the approved status AND they have items attached to their application, a link to complete the application will be sent via e-mail and text to the customer. This link opens the Koalafi UI where the customer will review and acknowledge their contract details, and then select the lease term they desire before going on to step 5.

5. Customer Signs Lease Agreement

Still on the Koalafi UI, after the customer has reviewed all payment and lease terms and has consented to entering the lease agreement, they will be shown the entire lease document. After reviewing the document, the customer can sign the lease at the bottom of the page.

Once the customer has signed the agreement, merchants should submit the purchase in their system for processing. You can verify that customer has signed the agreement by running the order query and checking for the docsSigned status. You also need to save the orderID you used throughout this application as you will need to have it to submit your lease for funding. Continue on to our Completing an Order page to learn about submitting a lease for funding.

Checkout with a Prequal Application

These are the steps for checking out via API, however, you can also complete checkout through our Koalafi Dealer Portal once you have completed Steps 1 and 2.

1. Update Employment

Next, we will need some additional information about the customer's employment. The customer will need to provide information about their pay frequency, last pay date, and next pay date which should be sent to Koalafi using updateEmployment mutation.

The input for this mutation will look like:

{
   "input":{
      "applicationId": 27645,
      "paymentFrequency": "monthly",
      "lastPayDate": "2022-09-09", 
     	"nextPayDate": "2022-10-09"
   }
}

updateEmployment is a small mutation that returns updateEmploymentResponse object which only contains updateEmploymentErrors.

An example mutation looks like:

mutation updateEmployment($input: UpdateEmploymentInput!) {
    updateEmployment(input: $input) {
      updateEmploymentErrors {
        __typename
        ... on FatalError {
          message
        }
        ... on BusinessError {
          message
        }
      }
    }
  }

A FatalError is returned when there is an error within Koalafi or one of our downstream dependencies. If you get a FatalError you can retry the mutation without making changes. If the mutation fails again, show a message to the customer asking them to try again at a later time.

A BusinessError occurs when there is an issue with the dates or frequency in the input. To prevent these errors, we recommend adding validation making sure that lastPayDate is a date within the last year and not a future date. For example, if today is January 10th, 2023 then they could enter a pay date between January 11th, 2022 and January 10th, 2023. If a BusinessError is returned, allow the customer the chance to adjust their employment information and then retry the mutation.

2. Update Bank Account

You can add the customer's banking information with the following mutation. Both accountNumber and routingNumber must be present in the input.

The following is an example input:

{
  "input": {
    "applicationId": 26065,
    "bankAccount" :{
    	"accountNumber": "0987654321",
      "routingNumber": "123456789"
    }
  }
}

updateBankAccount returns no response other than the errors list. A good example for this mutation looks like:

mutation updateBankAccount($input: UpdateBankAccountInput!) {
  updateBankAccount(input: $input){
    updateBankAccountErrors{
      __typename
      ... on FatalError{
        message
      }
      ... on BadRequest{
        message
      }
      ... on SoftDecline{
        message
        extensions {
          displayText
        }
      }
      ... on HardDecline{
        message
      }
    }
  }
}

Most of the time when you encounter an error, you will need to have the customer review their bank account data and then retry the mutation. Our Handling Common Errors page explains what the different error type represents as well as the specific messaging and steps to take to resolve the errors. Theses errors must be resolved before moving on to Step 3.

3. Update Debit Info

In the prequal flow, the lease approval returned from apply is a prequalifcation and in order to continue on with Koalafi financing, we need to run an authorization for an initial payment on their debit card. We will only charge the card after the customer has signed the lease agreement; if they choose not to sign the lease, the authorization will be removed.

You will only need to call updateDebitInfo if the apply call returned a lease with the status preApproved. If the lease was returned with a status of approved you can skip the updateDebitInfo call and just continue to Step 2.

We do not store the card details that were sent to us on apply so we will need the debitDetails to be resent along with the lease applicationId returned from apply, in an input that looks like:

{
   "input":{
      "debitDetails":{
         "cardholderFirstName":"Wally",
         "cardholderLastName":"Koala",
         "cardNumber":"4111111111111111",
         "expirationDate":"2023-05"
      },
      "applicationId": 25125
   }
}

The UpdateDebitInfoResponse object only returns updateDebitInfo errors so the mutation you send will be short but should listen for information on all possible errors.

mutation updateDebitInfo($input: UpdateDebitInfoInput!) {
  updateDebitInfo(input: $input) {
    updateDebitInfoErrors {
      __typename
      ... on FatalError {
        message
      }
      ... on HardDecline {
        message
      }
      ... on SoftDecline {
        message
      }
       ... on PrepaidCardError {
        message
      }
    }
  }
}

Most of the time when you encounter an error, you will need to have the customer review their debit data and then retry the mutation. Our Handling Common Errors page explains what the different error type represents as well as the specific messaging and steps to take to resolve the errors. Theses errors must be resolved before moving on to Step 4.

4. Add Items

Option A - Merchant Portal

At this point in the financing process, the store representative can login, pull up the customer's application in the portal and add merchandise to their lease.

Option B - Update Order Items

You can also add items via the updateOrderItems API call. The full instructions are listed in the non-prequal application section.

5. Customer Reviews and Acknowledges Contract Summary

Once a customer's app has reached the approved status AND they have items attached to their application, a link to complete the application will be sent via e-mail and text to the customer. This link opens the Koalafi UI where the customer will review and acknowledge their contract details, and then select the lease term they desire before going on to step 5.

6. Customer Signs Lease Agreement

Still on the Koalafi UI, after the customer has reviewed all payment and lease terms and has consented to entering the lease agreement, they will be shown the entire lease document. After reviewing the document, the customer can sign the lease at the bottom of the page.

Once the customer has signed the agreement, merchants should submit the purchase in their system for processing. You can verify that customer has signed the agreement by running the order query and checking for the docsSigned status. You also need to save the orderID you used throughout this application as you will need to have it to submit your lease for funding. Continue on to our Completing an Order page to learn about submitting a lease for funding.

Updated 2 days ago

What’s Next