Direct API

For customers who want to use their UI for application, checkout or both, the mutations below can be used to facilitate the full Direct API experience. Keep in mind that our APIs evolve over time so if you choose to use our direct API integration, you may occasionally need to make updates to continue to use our APIs.

Our API Update Strategy

  • Before removing any fields from our schema, we mark them as deprecated
  • We communicate any potential breaking changes and the estimated date of release so your team will have enough time to adjust to the changes

Below are all the steps needed to complete the Koalafi financing end to end. All mutations are bolded for clarity and can be cross-referenced with out API docs.

Create an Order and Apply for Financing

  1. Use the createOrder mutation to start all applications. This returns an orderID which will be used in all subsequent API calls for this customer.

  2. Use the customer query to look up the customer by their mobile phone number (required) , birthdate., last 4 tax ID or tax ID. In this query, we will check to see if the applicant is an existing Koalafi customer.

    1. If we do not recognize the customer, then they are eligible to continue on in the application process and you can skip to Step 3. The response for this scenario will look like the following:
    {
        "data": {
            "customer": {
                "customers": [],
                "eligibility": null,
                "customerSearchErrors": []
            }
        }
    }
    
    1. If the applicant is a returning Koalafi customer, the query does some additional steps to determine whether the applicant is eligible for Koalafi financing at this time. If you did not pass in birthdate or any taxID information you will get a response like below:

      {
          "errors": [
              {
                  "message": "customer is not authorized to retrieve application",
                  "path": [
                      "customer",
                      "eligibility",
                      "application"
                  ]
              }
          ],
          "data": {
              "customer": {
                  "customers": [
                      {
                          "id": 14517,
                          "firstName": "",
                          "lastName": "",
                          "cellPhone": "3324954040",
                          "emailAddress": null,
                          "tokenizedTaxId": null,
                          "birthDate": "",
                          "billingAddress": null
                      }
                  ],
                  "eligibility": {
                      "applyTypes": [],
                      "otbProducts": {
                          "loanOptions": [],
                          "leaseOptions": []
                      },
                      "isEligible": false,
                      "isLoanEligible": false,
                      "isLeaseEligible": false,
                      "application": null
                  },
                  "customerSearchErrors": []
              }
          }
      }
      

      This means we recognize the customer's phone number in our system but need more information to verify their identity. In order to verify the customer's identity please collect their birthdate and either the last 4 digits or their entire taxID and resubmit the customer query.

      1. Once we verify the customer in our system we check to see if they have any applications in progress and determine if they are eligible to apply for financing at this time. Some customers may also be eligible to use existing open lines and skip the application process all together. The important fields to check here are:

      2. isEligible: can be true or false

        1. If true - check otbProducts and if there are no options continue on with apply mutation
        2. If false - check application and if application is null customer is not eligible for financing at this time. No need to continue with the process.
      3. application: if application is not null, then the applicant has already been approved and does not need to be submitted again. An example of a response with an application in progress will look like:

        {
            "data": {
                "customer": {
                    "customers": [
                        {
                            "id": 22504,
                            "firstName": "Test",
                            "lastName": "Tester",
                            "cellPhone": "3324954041",
                            "emailAddress": "[email protected]",
                            "tokenizedTaxId": "4b417418-f6e7-4dca-9919-55ae404de9f0",
                            "birthDate": "1999-01-01",
                            "billingAddress": {
                                "line1": "123 S Cherry St",
                                "line2": null,
                                "city": "Richmond",
                                "state": "VA",
                                "zip": "23220"
                            }
                        }
                    ],
                    "eligibility": {
                        "applyTypes": [],
                        "otbProducts": {
                            "loanOptions": [],
                            "leaseOptions": []
                        },
                        "isEligible": false,
                        "isLoanEligible": false,
                        "isLeaseEligible": false,
                        "application": {
                            "lease": null,
                            "loan": {
                                "id": 2014942,
                                "isOtb": false,
                                "summary": null,
                                "status": "approved",
                                "options": [
                                    {
                                        "productID": 7,
                                        "deferredInterestPeriod": 0,
                                        "lineAmount": 10000,
                                        "merchantDiscountRate": "0.00",
                                        "minimumSpend": 300,
                                        "rate": "32.99",
                                        "termLength": 36
                                    }
                                ]
                            },
                            "customer": customer
                        }
                    },
                    "customerSearchErrors": []
                }
            }
        }
        

        If loan is not null you can skip to Loan Approval & Checkout section. If lease is not null , you can skip to Lease Approval & Checkout Section.

      4. otbProducts: customer has an open line available to them and does not need to go through the application process again. A successful OTB response will look like the following:

        {
            "data": {
                "customer": {
                    "customers": [
                        {
                            "id": 6847,
                            "firstName": "Thomas",
                            "lastName": "Jefferson",
                            "cellPhone": "7723845920",
                            "emailAddress": "[email protected]",
                            "tokenizedTaxId": "05efa3c2-235d-47bc-928b-7780ce48b555",
                            "birthDate": "2000-01-01",
                            "billingAddress": {
                                "line1": "931 Thomas Jefferson Parkway",
                                "line2": null,
                                "city": "Charlottesville",
                                "state": "VA",
                                "zip": "22902"
                            }
                        }
                    ],
                    "eligibility": {
                        "applyTypes": [
                            "leaseOTB"
                        ],
                        "otbProducts": {
                            "loanOptions": [],
                            "leaseOptions": [
                                {
                                    "leaseTerm": "12",
                                    "approvedAmount": "3000.00",
                                    "applicationFee": "",
                                    "earlyBuyoutDiscount": "30.00",
                                    "sacTerm": 0
                                }
                            ]
                        },
                        "isEligible": true,
                        "isLoanEligible": true,
                        "isLeaseEligible": true,
                        "application": null
                    },
                    "customerSearchErrors": []
                }
            }
        }
        

        If there are loan options returned, you can skip to Loan Approval & Checkout section. If there are lease options returned, you can skip to Lease Approval & Checkout Section.

  3. Collect the fields needed for the application through your UI, and send the application to Koalafi for a decision using apply mutation. If you are using this mutation as part of an approval first flow then you do not need to include any items in the customer’s cart but you will need to update the order with items prior to checkout. Apply returns ApplyResponse which looks like the following

"data":{
  "apply"{
    "application" : Application,
     "applicationErrors": [SubmitApplicationErrors]
  }
}
  1. If apply call encounters an error or the applicant is completely ineligibile for Koalafi financing application will be null and applicationErrors will be populated with a list with all errors. Please see Handling Common Errors to learn more about our different errors and what they mean

  2. If the apply call succeeds, then application will have a value which looks like :

"application": {
  "loan": null, 
  "lease": Lease, 
  "customer": Customer
}
  1. In the full spectrum flow, all applicants are first decisioned for a loan and only if they are declined for a loan decisioned for a lease. If an applicant is approved for a loan the response will look like :
"data":{
  "apply"{
    "application" : {
      "loan": Loan,
      "lease": null,
       "customer": Customer
    },
     "applicationErrors": null
  }
}

If you have a loan approval you can skip to Loan Approval & Checkout section.

  1. In full spectrum flow, If a customer was declined for a loan but approved for a lease the response will look like :
"data":{
  "apply"{
    "application" : {
      "loan": null,
      "lease": Lease,
       "customer": Customer
    },
     "applicationErrors": null
  }
}

If you have a lease approval you can skip to the Lease Approval & Checkout Section.

  1. In the loan only flow, applicants will only be decisioned for a loan. A successful response will look like
"data":{
  "apply"{
    "application" : {
      "loan": Loan,
      "lease": null,
       "customer": Customer
    },
     "applicationErrors": null
  }
}
  1. In the lease only flow, applicants will only be decisioned for a lease. A successful response will look like
"data":{
  "apply"{
    "application" : {
      "loan": null,
      "lease": Lease,
       "customer": Customer
    },
     "applicationErrors": null
  }
}

Loan Approval & Checkout

  1. At this point a customer has been approved for a loan. Customers can be approved for multiple loan products, which will be returned as part of the apply response. Use selectLoanOptionType to designate which product the customer will be using, which will determine the payment details of their loan.

  2. If a customer has had the chance to update their cart since approval you need to call updateOrderItems before checkout to sync the Koalafi cart with your site’s. Please note it is not necessary to call updateOrderItems after every cart change, we only need the final cart.

  3. After the loan is fully created, you can generateContract for review of all payment and loan details.

  4. Once the customer reviews the loan agreement, you will need to capture their consent with signLoanAgreement. Once the customer has signed the agreement, merchants should submit the purchase in their system for processing.

  5. 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 at Step 2 and repeat all the subsequent steps. This is important because it ensures that loan agreement the customer signs matches the price of the purchases they’re making on your site.

Lease Approval & Checkout

  1. At this point your customer has been approved for a lease. If a customer has had the chance to update their cart since approval you need to call updateOrderItems before checkout to sync the Koalafi cart with your site’s. Please note it is not necessary to call updateOrderItems after every cart change, we only need the final cart.

  2. Next, we will need some additional information about the customer to account for the differences in leases and loans. The customer will need to provide information about their pay frequency and last pay date, which should be sent to Koalafi using updateEmployment mutation.

  3. If the customer's shipping address is different from the billing address provided in the application, provide their shipping address to Koalafi using updateShippingAddress. This ensures we pay taxes to the correct states.

  4. At this point, the customer will need to provide a debit card that will be authorized for the initial payment. This is used to verify a payment source. We will attempt to authorize a charge for the initial payment on the debit card provided as soon as you call updateDebitInfo, and charge the card once the customer signs the lease agreement. If the lease is not signed, the authorization will be removed. We do not accept prepaid cards. See Handling Common Errors for how to handle a debit card errors.

  5. Once we successfully confirm the employment, shipping address and debit card provided by the customer, you will be able to generate payment terms and the lease document with generateContract.

  6. After the customer has reviewed all payment and lease terms and has consented to entering the lease agreement, capture their consent using signLeaseAgreement. Once the customer has signed the agreement, merchants should submit the purchase in their system for processing.

  7. 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 loan agreement the customer signs matches the price of the purchases they’re making on your site.

Completing an Order

Once you have delivered the purchased items to the customer, use markOrderDelivered to notify Koalafi that the customer has the merchandise and the loan/lease should be funded. Customers will start making payments on their loan/lease after delivery is completed