Use case for expense management

Use Wafeq's API to push expenses from an expense management software into Wafeq.

Use case overview

We'll implement an integration for a fictitious expense management app called Expensico.

Expensico is a software that issues corporate cards to employees. It also allows employees to file expense claims they paid out of pocket to be reimbursed.

Expensico developers want to build an integration with Wafeq to automate booking expenses for accounting purposes.
They want the integration to do the following:

  • When an expense report is approved by a manager, automatically create the expenses in Wafeq.
  • If an expense is to be reimbursed, book it under an Expensico – Employee Claims account.
  • If an expense is paid through an employee card, book it against an Expensico – Employees Balance asset account. This is the account that keeps track of the total money available in employee cards.
  • Any money movement in and out the bank account (such as top ups or reimbursements) that funds employee cards will be recorded in an Expensico Bank Account bank account in Wafeq.

Suggested implementation


This step is performed by the user initially when setting up the integration.
You will need to do the following:

  1. Ask the user to connect their Wafeq account using the flow described in the {% relink text="Authorization section" href="/docs/introduction/authorization" /%}. Store the access token in your database to make API calls on behalf of your user.
  2. {% relink text="Get the list of accounts" href="/docs/api-reference/accounts" /%} filtered on the EXPENSE classification for the organization
  3. Ask the user to map these accounts to their expense categories in your software
  4. Ask the user to choose the CURRENT_LIABILITY account in Wafeq to use to record employee claims, or offer to create one for him. Call it something easy to recognize as belonging to Expensico, such as Expensico – Employee Claims and make sure is_payment_enabled field set to true.
  5. Ask the user to choose the CURRENT_ASSET account in Wafeq to use to record expenses paid through employee cards, or offer to create one for him. Call it something easy to recognize as belonging to Expensico, such as Expensico – Employees Balance and make sure is_payment_enabled field set to true.
  6. Ask the user to choose the Bank Account that represents the bank account that funds employee cards, or offer to create one for him. Call it something easy to recognize such as Expensico Bank Account.

Save the above configuration in your database. You're now ready to sync.

Syncing expenses

Once the configuration is done, you'll want to decide when you want create an expense in Wafeq.
For example, when an expense report is approved:

  • Use the {% relink text="Expenses endpoint" href="/docs/api-reference/expenses" /%} to create each expense in the expense report
    • Use the reference field as a unique identifier for expenses you create. You will use this field to look up an expense before you create it to avoid duplication
    • Set the paid_through_account based on whether the expense is a claim or paid using the Expensico – Employees Balance account.

Syncing statement bank transactions

You'll want to create statement bank transactions to make it easy for the user to reconcile the statement, instead of asking them to import the statement manually.

To do that, create a {% relink text="statement bank transaction" href="/docs/api-reference/bank-statements" /%} for each statement transaction for the bank account Expensico Bank Account.

Syncing ledger bank transactions

For each transaction type below, create a ledger bank transaction in Expensico Bank Account with the account field set as follows:

Transaction typeDescriptionAccount
ReimbursementsWhen an employee is reimbursedExpensico – Employee Claims
Card fundingWhen a card is fundedExpensico – Employees Balance

Manual sync

After the configuration is completed, you'll want to allow the user to perform a sync of historical expenses into Wafeq. One possible implementation is as follows:

  • Allow the user to select a date range to sync approved expense reports
  • For each expense in each expense report, check if it already exists in Wafeq by looking it up by reference. If it does not exist, create it.
  • Perform a full Expensico Bank Account statement sync
  • Create ledger bank transactions for Expensico Bank Account