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 software. 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 requires a lender bank account - a virtual account that contains the lender's transactions. This account, also known as a container, clearing, or drawdown account, is used to manage and track funds related to lending activities.

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 software

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​

The loan writeback process uses two bank accounts:

  • A borrower's business bank account where the money lent is deposited.
  • A lender's bank account, which is a virtual account in the accounting software that serves as a container for lender transactions. This account is created when setting up the bank feed source account.

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: companyId,
    connectionId: connectionId
}).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.

Supplier​

In order to create a spend money transaction, Codat requires you, the lender, to be represented as a supplier 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: companyId,
}).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 software.

  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 software.
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: companyId,
    connectionId: connectionId,
    }).then((res: CreateSupplierResponse) => {
    if (res.statusCode == 200) {
        // handle response
    }
});

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

Expense account​

Next, 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: companyId,
    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: companyId,
connectionId: connectionId,
}).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.

Bank feed source account​

Finally, you’ll need to create and map a source account to enable bank feed transactions that the SMB can reconcile in their accounting software. This two-step process establishes the lender’s bank account, defined as lendersBankAccountId in your solution.

Create source account​

To create the lender’s bank account, start by setting up a source account in the loan's agreed currency. Ensure it has a zero balance and specify an ID and account number of your choice.

UK-specific requirements: For bank accounts in GBP, sortCode is also a required field.

const sourceAccountResponse = bankFeedsClient.sourceAccounts.create({
    sourceAccount: {
      id: "bank-of-dave-lenders-account",
      accountName: "Bank of Dave - loan account",
      accountType: "loan",
      accountNumber: "66260701",
      currency: loanCurrency,
      balance: 0.00
    },
    companyId: companyId,
    connectionId: connectionId
  });

const lendersBankAccountId = sourceAccountResponse.oneOf.sourceAccountV2.id;

Map source account​

The second step to complete the setup of the lender’s account in the accounting software is to create a representation of the source account. This is achieved by mapping the source account without assigning a target account. When no target account is specified, one will be created automatically.

const mappingResponse = await codatLending.loanWriteback.sourceAccounts.createMapping({
    companyId: companyId,
    connectionId: connectionId,
    bankFeedBankAccountMapping: {
      sourceAccountId: lendersBankAccountId,
    },
  });
  • Learn how to deposit the lent funds into your SMB's accounting software.
Was this page useful?
👏
👍
🤔
👎
😭

Contents

Suggest edits