This is a staging build of the docs. Do not share the link externally.
Skip to main content

Configure your solution

Create key elements of loan writeback in Codat's domain and enable your SMB customer to map them

Once your SMB customer's loan has been approved, provide them with a user interface that lets them optionally enable the loan writeback and configure loan writeback accounts so that the accounting entries are reflected correctly in their accounting platform. They will create or select existing, and subsequently map, the following elements:

  • SMB bank account, the borrower's business account where the loan is deposited.
  • Expense account, an account to record incurred fees and interest.
  • Supplier record, a record to identify you, the lender, in future transactions.

Your solution also needs a lender bank account, a virtual account that contains the lender's transactions. You would have created this source account when implementing bank feeds. Now, map it to a target account in your SMB customer's accounting platform. You can define it as lendersBankAccount in your solution.

Let your customers take control

In some cases, the SMB's bookkeeper will want to manage their accounts themselves. To do this, make sure to offer your customers the option to disable loan writeback for manual reconciliation.

For example, your user interface might look something like this:

Example mapping UI

Map your loan writeback components to a relevant account.

Deposit account

Select the business bank account where the funds will be deposited.

Expense account

Select or create the expense account you want any fees or interest tracked against.

Lender account

We'll also create a new bank account in your accounting platform

This account acts as the lender's virtual account and is used for double-entry accounting purposes.

Let's go through this process in detail. On the diagram below, you can see the configuration sequence covering the display and selection of a bank account, an expense account, and a supplier record. Alternative steps are also provided in case a new account and a new supplier need to be created.

Bank account​

Loan writeback process operates with two bank accounts:

  • A borrower's business bank account where the money lent is deposited.
  • A lender's bank account, which is a virtual bank account in the accounting platform that acts as a container for lender transactions.

First, your customer needs to choose one of their existing business bank accounts. This account will be used to depost the loan. Call our List bank accounts endpoint to retrieve the customer's existing bank accounts. 

codatLending.accountingBankData.accounts.list({
    companyId: "8a210b68-6988-11ed-a1eb-0242ac120002",
    connectionId: "2e9d2c44-f675-40ba-8049-353bfcb5e171"
}).then((res: ListAccountingBankAccountsResponse) => {
if (res.statusCode == 200) {
    // handle response
}
});

Display the response to the customer and allow them to select the account. Store the returned bank account as borrowersBankAccount and use it to access properties on the borrower's bank account in future operations.

For the lender's bank account, use the lendersBankAccount value you would have created when implementing

The fallback content to display on prerendering
.

Supplier​

In order to create a spend money transaction, Codat requires you, the lender, to be represented as a

The fallback content to display on prerendering
in your SMB's accounting system.

Let your customer check if your record already exists in their accounts. Use our List suppliers endpoint to fetch the list of existing suppliers. 

codatLending.accountsPayable.suppliers.list({
    companyId: "8a210b68-6988-11ed-a1eb-0242ac120002",
}).then((res: ListAccountingSuppliersResponse) => {
if (res.statusCode == 200) {
    // handle response
}
});

Display the response to the customer and allow them to find and select your lender record in their supplier list. Store the supplier id as supplier and use it in future transactions.

If this is the first time you have lent to this SMB customer, you may need to create yourself as a new supplier in their accounting platform.

  1. Use our Get create/update supplier model to get the expected data for the supplier creation request payload. The data required can vary depending on the platform.
  2. Use that payload to call the Create supplier endpoint to create the new supplier record in the accounting platform.
codatLending.loanWriteback.suppliers.create({
    accountingSupplier: {
        addresses: [
        {
            line1: "Stoney Business Park",
            city: "London",
            country: "UK",
            postalCode: "SE14 1PE",
            type: AccountingAddressType.Billing,
        },
        ],
        contactName: "David",
        defaultCurrency: "GBP",
        emailAddress: "david@example.com",
        phone: "+44 25691 154789",
        registrationNumber: "0115633",
        status: SupplierStatus.Active,
        supplierName: "Bank of Dave",
    },
    companyId: "8a210b68-6988-11ed-a1eb-0242ac120002",
    connectionId: "2e9d2c44-f675-40ba-8049-353bfcb5e171",
    }).then((res: CreateSupplierResponse) => {
    if (res.statusCode == 200) {
        // handle response
    }
});

Similarly, store the supplier and use it in future transactions.

Expense account​

Finally, use our List accounts endpoint filtered by type=Expense to retrieve the customer's existing expense accounts. Let them choose one that will be used to record fees and interest. 

codatLending.financialStatements.accounts.list({
    companyId: "8a210b68-6988-11ed-a1eb-0242ac120002",
    query: "type=Expense",
}).then((res: ListAccountingAccountsResponse) => {
if (res.statusCode == 200) {
    // handle response
}
});

Display the response to the customer and allow them to select the desired expense account. Store the account as expenseAccount and use it as the expense account in future operations.

If the customer wants to create a new nominal expense account for this purpose, use our Get create account model to figure out what payload is required for account creation.

Next, call the Create account endpoint to create the new account. 

codatLending.loanWriteback.accounts.create({
accountingAccount: {
    currency: "USD",
    currentBalance: 0,
    description: "Invoices the business has issued but has not yet collected payment on.",
    fullyQualifiedCategory: "Asset.Current",
    fullyQualifiedName: "Cash On Hand",
    name: "Accounts Receivable",
    nominalCode: "610",
    status: AccountStatus.Active,
    type: AccountType.Asset,
    
},
companyId: "8a210b68-6988-11ed-a1eb-0242ac120002",
connectionId: "2e9d2c44-f675-40ba-8049-353bfcb5e171",
}).then((res: CreateAccountResponse) => {
if (res.statusCode == 200) {
    // handle response
}
});

In response, you will receive account creation details which you can display to your customer. Similarly, store the account as expenseAccount for use in future transactions.

  • Learn how to deposit the lent funds into your SMB's accounting platform.
Was this page useful?
❤️
👍
🤔
👎
😭

Contents

Suggest edits