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.
Merchant Portal
Before switching over to the merchant portal you will need to make one API call so that the application can successfully be resumed from our 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.
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 2.
2. Continue on Merchant Portal
At this point in the financing process, the store representative can login, pull up the customer's application in the portal and finish our the financing process with the customer in the store.
APIs
1. 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.
2. Update Order Address
If the customer's shipping address was not included in the initial application, add their shipping address to their Koalafi application using updateOrderAddress. You will need to pass both shippingAddress and billingAddress in the input. If you do not have the ability to collect a customer's shipping address then you can pass their billing address as their shipping address.
The following is an example input:
{"input": {
"orderId": "< your orderID> ",
"billingAddress": {
"line1":"1800 Dingus Way",
"city":"Powhatan",
"state":"VA",
"zip": "23138"
},
"shippingAddress": {
"line1":"861 UPS Way",
"city":"Powhatan",
"state":"VA",
"zip": "23138"
}
}
}
updateOrderAddress returns the updateOrderAddressResponse object which is made up of order and updateOrderErrors. For this use case you can ignore order and only need to check for a few updateOrderError types. A good example for this mutation looks like:
mutation UpdateAddress($input: UpdateOrderAddressInput!) {
updateOrderAddress(input: $input){
orderErrors{
__typename
... on FatalError{
message
}
... on BadRequest{
message
}
... on NotFound{
message
}
}
}
}
If 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.
If a BadRequest or NotFound error is returned, you'll need to adjust the input and retry the mutation.
3. 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":"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. 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.
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.
Cart Changes
If the customer changes their cart at all prior to submitting the purchase in your system, then you’ll need to start this section again and repeat all these steps. This is important because it ensures that lease agreement the customer signs matches the price of the purchases they’re making on your site.
Updated 27 days ago