Deposit and Withdrawal Operations

This document describes the mechanics of recording deposits and processing withdrawals, including the approval workflow, ledger entries, and reversal capabilities.

Deposit Operations

How Deposits Work

A deposit represents an inbound fund movement into a customer's account. Deposits are recorded by operators when external funds have been received (e.g., via wire transfer, check, or other settlement mechanism). The system does not initiate the actual fund movement; it records the fact that funds have arrived.

When a deposit is recorded:

1. The system validates that the deposit account is active and the amount is non-zero.
2. A new deposit entity is created with status Confirmed.
3. A ledger transaction posts two entries on the settled layer.
4. The deposit is immediately available in the customer's balance.

Deposit Accounting Entry

Account	Debit	Credit	Layer
Deposit Omnibus (Asset)	X		Settled
Customer Deposit Account (Liability)		X	Settled

The omnibus account (the bank's cash/reserves) increases on the debit side, and the customer's deposit account (a liability the bank owes to the customer) increases on the credit side.

Deposit Reversal

If a deposit was recorded in error, it can be reverted. Reversal posts the inverse ledger transaction (credit the omnibus, debit the customer account), returning both accounts to their pre-deposit state. The deposit entity transitions to Reverted status. Reversal is idempotent: reversing an already-reverted deposit has no effect.

Withdrawal Operations

Withdrawal Lifecycle

Withdrawals are more complex than deposits because they require governance approval before funds are released. The full lifecycle involves encumbering funds at initiation, waiting for approval, and then confirming or cancelling the withdrawal.

Status	Description
Pending Approval	Withdrawal initiated, funds encumbered, payout drafted, awaiting governance decision
Pending Confirmation	Governance approved, payout submitted to the rail, awaiting settlement
Confirmed	Funds released, withdrawal complete
Denied	Governance rejected the withdrawal, funds restored
Cancelled	The withdrawal's payout failed or was cancelled before settling, funds restored
Reverted	Previously confirmed withdrawal reversed, funds restored

Step-by-Step Withdrawal Flow

1. Initiation - An operator initiates a withdrawal by specifying the amount and an optional reference. The system:

• Validates that the account is active and the amount is non-zero.
• Checks the deposit account agreement's copied product terms. If the amount exceeds maxWithdrawalAmountPerTransaction, the request is rejected before creating the withdrawal, approval process, ledger entries, or exchange-rate lookup.
• Drafts the payout that will execute the withdrawal: the payment rail and provider for the destination are resolved and pinned, and the account's funding source is recorded. If no rail serves the destination, the request is rejected. The draft encumbers the amount on the rail's outbound liquidity in the payments journal and contacts no provider; it exists so an approver can see exactly what would execute.
• Creates a governance approval process (type: withdraw).
• Posts an INITIATE_WITHDRAW ledger transaction that moves funds from settled to pending.
• The customer's settled balance decreases immediately, preventing the funds from being used for other operations.

2. Approval - The governance system processes the withdrawal according to the configured policy:

• If the policy is AutoApprove, the withdrawal is approved instantly.
• If the policy uses CommitteeThreshold, committee members must vote to approve or deny.
• A single denial from any committee member immediately rejects the withdrawal.
• This step happens asynchronously via the event-driven job system.
• On approval, the drafted payout is submitted on its pinned rail and its encumbrance becomes an in-flight (pending) claim. On denial, the draft is closed and its hold on the rail is released.

3a. Confirmation - After approval, the withdrawal is confirmed when its payout settles on the rail (reported by the payment provider, or marked settled by an operator for out-of-band rails). A CONFIRM_WITHDRAW ledger transaction clears the pending balance.

3b. Cancellation - A withdrawal is cancelled when its payout fails or is cancelled on the rail before settling. A CANCEL_WITHDRAW ledger transaction reverses the encumbrance, restoring the settled balance. Withdrawals are not cancelled or confirmed directly: once approved, the payout decides the outcome; before approval, governance denial stops the withdrawal.

3c. Denial - If governance denies the withdrawal, a DENY_WITHDRAW ledger transaction automatically reverses the encumbrance, identical in effect to cancellation, and the drafted payout is closed.

4. Reversal (optional) - A confirmed withdrawal can be reversed if the external fund movement failed or was returned. A REVERT_WITHDRAW ledger transaction restores the settled balance.

Withdrawal Accounting Entries

The withdrawal process uses four different ledger templates depending on the stage:

Initiation (encumber funds)

Account	Debit	Credit	Layer
Deposit Omnibus (Asset)		X	Settled
Customer Deposit Account (Liability)	X		Settled
Deposit Omnibus (Asset)	X		Pending
Customer Deposit Account (Liability)		X	Pending

This moves the amount from settled to pending on both the omnibus and customer accounts.

Confirmation (release funds)

Account	Debit	Credit	Layer
Deposit Omnibus (Asset)		X	Pending
Customer Deposit Account (Liability)	X		Pending

Clears the pending encumbrance. The settled balance was already reduced at initiation.

Cancellation or Denial (restore funds)

Account	Debit	Credit	Layer
Deposit Omnibus (Asset)		X	Pending
Customer Deposit Account (Liability)	X		Pending
Deposit Omnibus (Asset)	X		Settled
Customer Deposit Account (Liability)		X	Settled

The exact inverse of initiation: clears pending and restores settled.

Reversal (undo confirmed withdrawal)

Account	Debit	Credit	Layer
Deposit Omnibus (Asset)	X		Settled
Customer Deposit Account (Liability)		X	Settled

Restores the settled balance as if the withdrawal never happened.

Admin Panel Walkthrough: Deposits and Withdrawals

This flow shows operational creation and management of deposits and withdrawals.

A) Create a deposit

Step 1. Click global Create.

Step 2. Select Create Deposit.

Step 3. Enter deposit amount.

Step 4. Submit.

Step 5. Confirm success message.

Step 6. Verify deposit in deposit list.

Step 7. Verify deposit in customer transaction history.

B) Create a withdrawal

Step 8. Click Create for withdrawal initiation.

Step 9. Select Create Withdrawal.

Step 10. Enter withdrawal amount.

Step 11. Submit the request.

Step 12. Verify withdrawal appears in withdrawal list.

Step 13. Verify withdrawal appears in customer transactions.

C) Manage withdrawal outcome

Cancel a pending withdrawal

Step 14. Click Cancel.

Step 15. Confirm cancellation.

Step 16. Verify status becomes cancelled.

Approve a pending withdrawal

Step 17. Click Approve.

Step 18. Confirm approval.

Step 19. Verify approved/confirmed status.