This is a staging build of the docs
We've reorganized our products to make building with Codat easier than ever
Skip to main content

Bank transactions

Once a company has mapped their source account to a target account, you can begin pushing transactions to their bankfeed.

Generate bankTransactions object​

Before you can record the companies bankTransactions in their accounting platform, you'll need to generate a transactions object for each transaction that has been made from their account.

The bankTransaction object must only contain transactions that have cleared and should not include any pending or upcoming transactions.

At the top level of the bankTransactions object, you should include the sourceAccount id of for the transactions to be associated with.

Each transaction within the transactions array should include the following:

  • id this is a string and should be your unique identifier for a given transaction.
  • amount the amount of the transaction, if its spending money (Debit) then the signage should be negative (e.g. -42.00).
  • balance the balance of the account in the given currency after the given transaction, often platforms use this to represent the balance of the account.
  • date the date the transaction took place, all transactions in the object should be ordered oldest to newest.
  • description a short description of the transaction, this could include details such as the merchant or the exchange rate if its in a foreign currency.
  • transactionType supports Debit to show money leaving the account and Credit to represent money coming into the account.
Transaction Signs

Make sure the transaction amount signs align with the transactionType. Codat issues a warning for inconsistencies, such as a Debit transaction with a positive amount.

Push bank transactions​

Steps:

Create bankTransactions​

Regularly uploading transactions throughout the day ensures that your customers' bank feed balances are close to real-time. This enhanced accuracy aids companies with increased accuracy for their planning and forecasting.

Use the create-bank-transactions endpoint

POST /companies/:companyId/connections/:connectionId/push/bankAccounts/:accountId/bankTransactions

When you make the request, you will receive a pushOperation response with a Pending status and 202 statusCode, the pushOperation object will include the following information:

  • pushOperationKey: a unique idempotent identifier generated by Codat to represent this single pushOperation that can be used to track its status
  • dataType: the type of data being created, in this case, bankTransaction
  • status: the status of the create operation, which can be Pending, Failed, Success or TimedOut
  • requestedOnUtc: the datetime (in UTC) when the operation was requested
  • completedOnUtc: the datetime (in UTC) when the operaion was completed, null if Pending
  • validation: a human-readable object that contains validation details, including errors, encountered during the operation.
  • changes: an array that communicates which record has changed (recordRef property) and the manner in which it changed (type property that can be Unknown, Created, Modified, or Deleted)
QuickBooks Online Bank Feeds Syncing Info

Transactions pushed to QuickBooks Online bank feeds will show a 'Success' status once validated and saved by Codat.

These transactions will only become available to the user in their accounting software after synchronization between QBO and Codat.

Users can manually sync from the QBO interface, and QBO will also automatically poll Codat daily for updates.

Monitor the status of the request​

After your request has been accepted, it will have a status of Pending. You should use the Push Operation Status Changed webhooks to track when the status of your pushOperation changes to Success or Failed.

If the request is successful, you will receive a webhook like this:

{
 "CompanyId":"c2dddf4c-eece-4a9b-a392-8c8e65b59e47",
 "RuleId":"5a6f112d-b0fa-4c0b-9ea4-7dd4075bc43d",
 "Type":"Push Operation Status Changed",
 "AlertId":"a6bb69d5-631c-4732-8e4e-18bea36aea20",
 "Message":"bankTransactions triggered notification for PushOperationStatusChanged at 2023-09-12T18:19:42.742Z",
 "Data":{
    "dataType":"bankTransactions",
    "status":"Success",
    "pushOperationKey":"e881111f-b6a4-4740-b125-340a6c300cd3"
    }
}

If you want to see a history of all pushOperations for your company, you can retrieve these from the list-push-operations endpoint.

Was this page useful?
❤️
👍
🤔
👎
😭

Contents

Suggest edits