Import and account for bank transactions

Wafeq exposes the bank statement and accounting ledger as related but distinct records:

• A statement transaction represents what the bank reported.
• A ledger transaction represents how that movement is categorized in the books.

Keeping the distinction makes reconciliation possible and prevents a bank feed from silently deciding the accounting treatment.

1. Resolve the bank account

List Bank accounts and store the Wafeq bank-account ID next to the external bank-feed connection.

Never identify a bank account only by display name.

2. Import the statement transaction

curl --request POST "https://api.wafeq.com/v1/bank-accounts/<BANK_ACCOUNT_ID>/statement-transactions/" \
  --header "Authorization: Api-Key <API_KEY>" \
  --header "Content-Type: application/json" \
  --header "X-Wafeq-Idempotency-Key: statement-<BANK_TRANSACTION_ID>" \
  --data '{
    "date": "2026-08-29",
    "amount": -250,
    "statement_balance": 18450,
    "description": "Cloud hosting",
    "bank_reference": "BANK-77821",
    "reference": "feed_77821"
  }'

Use the amount sign and balance convention defined by your bank connector and the Create bank statement transaction schema. Test both incoming and outgoing examples before importing historical data.

3. Create the accounting entry

When the transaction is categorized:

curl --request POST "https://api.wafeq.com/v1/bank-accounts/<BANK_ACCOUNT_ID>/ledger-transactions/" \
  --header "Authorization: Api-Key <API_KEY>" \
  --header "Content-Type: application/json" \
  --header "X-Wafeq-Idempotency-Key: ledger-<BANK_TRANSACTION_ID>" \
  --data '{
    "date": "2026-08-29",
    "amount": -250,
    "account": "<EXPENSE_ACCOUNT_ID>",
    "description": "Cloud hosting",
    "reference": "feed_77821",
    "contact": "<SUPPLIER_CONTACT_ID>",
    "tax_rate": "<TAX_RATE_ID>",
    "project": "<PROJECT_ID>"
  }'

Use Bank ledger transactions for accounting-side entries and Bank statement transactions for feed-side records.

Reconciliation strategy

The public API exposes both sides of the bank account. If your integration does not implement a supported matching action, import the statement data and let finance users reconcile it in Wafeq.

A robust matching candidate typically compares:

• Bank account
• Signed amount and currency
• Date within an allowed window
• Bank reference or source transaction ID
• Contact and description

Do not create a new ledger transaction merely because the statement line was re-delivered by the bank.

Incremental bank sync

1. Store the external bank transaction ID in reference and in your own mapping table.
2. Use a stable idempotency key when creating the statement line.
3. Page through all list results.
4. Pull modified records again after reconciliation or accounting edits.
5. Maintain separate checkpoints for statement and ledger transactions.

For adjustments that do not originate in a bank feed, see Post journals and read financial reports.