Withdrawals

Withdrawals transfer available balance from an entity's account to their external bank account or crypto address. Any earning entity (merchant, tenant, or partner) can request a withdrawal of their accumulated funds.

Withdrawal vs Settlement vs Payout

These three operations are distinct. Understanding the difference is essential.

Operation	What it does	Who initiates	Approval
Settlement	Produces a financial statement summarizing transactions, fees, and net amounts for a period	System (automatic) or operator (manual)	Auto-finalized or operator review
Availability Transition	Moves funds from `pending` to `available` balance on a T+N schedule	System (daily cron job)	None required
Withdrawal	Transfers available balance to an external bank account	Entity (merchant, tenant, or partner)	Merchant/partner: operator approval required. Tenant: self-approved
Payout	Sends money to a third-party recipient (e.g., seller, affiliate)	Merchant via API	Per merchant configuration

Settlement is a financial statement document. See Settlements.
Availability Transition (T+N) makes funds available for withdrawal.
Withdrawal is the entity pulling out their own money.
Payout is a service product where the merchant pays someone else.

Withdrawal Flow

A withdrawal goes through two distinct financial steps: approval (balance reservation) and execution (actual fund transfer). These are separate operations with different ledger effects.

Merchant or Partner Withdrawal

Request: The merchant or partner creates a withdrawal request in the Portal or via API. Status: pending. No funds are reserved yet.
Review: An operator sees the request in the pending approvals queue.
Approve or Reject: The operator reviews the amount, destination, and available balance, then approves or rejects. Rejection requires a reason.
- On approval: the system reserves the withdrawal amount by moving it from the entity's available balance to the payable bucket. This is an internal balance transfer only -- no money leaves the platform yet.
- On rejection: no ledger entries are created. The request reaches a terminal state.
Execution: A separate step after approval. The operator starts execution, and the system transfers the net amount (withdrawal amount minus fee) from the tenant's FundingAccount to the entity's external bank account. The fee is recorded as a separate ledger entry on the terminal clearing account.
Completion or Failure: Once the bank transfer succeeds, the withdrawal is marked as completed and the payable reservation is cleared. If the transfer fails, the payable reservation is reversed back to available.

Tenant Withdrawal

Request: The operator creates a withdrawal request for the tenant's own earnings. Status: pending.
Self-approval: Tenant withdrawals are auto-approved (the tenant controls their own funds). Balance moves from available to payable.
Execution: The operator starts execution. The system transfers funds from the FundingAccount to the tenant's external account. No fee is charged -- tenants do not charge themselves.
Completion: Marked as completed on success, or failed if the transfer does not go through.

There are no automatic withdrawals. Balance accumulates until the entity explicitly requests a withdrawal.

Approval vs Execution: What Happens to the Money

Step	Ledger effect	Money leaves platform?
Approval	Debit entity `available`, credit entity `payable` (internal bucket transfer)	No
Execution (completion)	Debit entity `payable`, credit FundingAccount `available` (net payout), credit terminal `operational` (fee)	Yes
Execution (failure)	Reverse payable reservation back to `available`	No

Withdrawal Statuses

Status	Meaning
`pending`	Request created, awaiting operator approval. No funds reserved.
`approved`	Operator approved. Funds reserved in `payable` bucket. Ready for execution.
`rejected`	Operator denied the request (reason provided). No ledger entries. Terminal state.
`canceled`	Entity self-canceled. Terminal state.
`executing`	Transfer sent to provider or manual execution in progress.
`completed`	Funds successfully transferred to recipient. Payable cleared. Terminal state.
`failed`	Provider rejected the transfer or execution timed out. Payable reversed to available. Terminal state.

Status Diagram

pending ──→ approved ──→ executing ──→ completed
  │             │                  └──→ failed
  ├──→ rejected │
  ├──→ canceled │
  │             └──→ canceled

Key constraints:

rejected is only reachable from pending.
canceled is reachable from pending or approved, but not from executing. Once execution starts, it must complete or fail.
executing can only transition to completed or failed. There is no way to cancel a withdrawal that is already executing.

Withdrawal Fees

Net payout model

The withdrawal fee is deducted from the withdrawal amount. The entity receives amount - fee.

Example: A merchant requests a withdrawal of EUR 92.39. The fee is EUR 1.00.

Entity receives: EUR 91.39
Fee retained by tenant: EUR 1.00
Total debited from entity's available balance: EUR 92.39 (the full requested amount)

Tenant self-withdrawals

Tenant self-withdrawals have no fee. The tenant does not charge themselves for withdrawing their own earnings. The fee field is recorded as zero.

Fee calculation timing

The fee is calculated by the billing engine at withdrawal creation time (when the request enters pending). The fee is locked at creation and does not change on approval or execution. The fee schedule and fee rule used are recorded on the withdrawal request for audit purposes.

Withdrawal Destinations

When creating a withdrawal, the entity specifies a destination:

Bank account:

IBAN
SWIFT/BIC
Account holder name

Crypto wallet (future):

Wallet address
Network

Saved withdrawal methods

Entities can save withdrawal methods so they do not need to re-enter details each time. Saved methods are managed per merchant.

48-hour cooling period: When a new withdrawal method is added or its destination details are changed, the method enters a cooling status for 48 hours. During this period, it cannot be used for withdrawals. After 48 hours, the status transitions to active automatically. This protects against account takeover -- if an attacker adds a new bank account, there is a window for the legitimate owner to notice and remove it.

Method status	Can be used for withdrawal?
`cooling`	No. Waiting for 48h cooling period to expire.
`active`	Yes.
`suspended`	No. Manually suspended by operator.

Balance Guards

Before a withdrawal is approved, the system checks:

Available balance: The entity must have sufficient available balance to cover the withdrawal amount plus any withdrawal fee.
Withdrawal limits: Daily, weekly, and monthly limits are configured per withdrawal channel (not per entity). Each WithdrawalChannel has its own dailyMax, weeklyMax, and monthlyMax limits. If the withdrawal would exceed any of these channel-level limits, it is blocked.
Liquidity guard (tenant withdrawals only): Ensures the FundingAccount has sufficient unobligated funds. The system verifies that FundingAccount.available - totalEntityObligations >= withdrawalAmount to prevent the tenant from draining merchant or partner funds.

If any guard fails, the withdrawal request is rejected with a clear reason.

Approval Workflow

In the Portal, operators manage withdrawal approvals:

Navigate to Withdrawals in the Portal.
Filter by status pending to see requests awaiting approval.
Review each request: entity, amount, destination, available balance.
Click Approve to reserve the funds (moves balance from available to payable), or Reject with a mandatory reason.

After approval, the withdrawal must still be executed as a separate step:

Click Start Execution on an approved withdrawal. This locks the withdrawal to the executing operator (mutual exclusion).
Perform the bank transfer externally (manual execution in current phase).
Click Mark Completed with a required comment (e.g., wire reference number), or Mark Failed with a reason if the transfer did not succeed.

Merchant and partner withdrawals always require operator approval. Tenant withdrawals are self-approved and skip the approval queue.

Cancellation

An entity can cancel their own withdrawal request:

From pending status: cancellation creates no ledger entries. No funds were reserved.
From approved status: the payable reservation is reversed and funds return to available.
Once a withdrawal reaches executing status, it cannot be canceled. It must complete or fail.

Mass Withdrawals

For tenants processing many merchant withdrawals, the system supports batch operations. An operator can approve multiple pending withdrawals at once rather than handling each individually.

Key Points

Withdrawals move money OUT of the platform to an external account.
Approval and execution are separate steps. Approval reserves funds internally; execution transfers them externally.
Merchants and partners need operator approval. Tenants self-approve.
Available balance must cover the amount plus fees.
Fees follow a net payout model: the entity receives the withdrawal amount minus the fee. Tenant self-withdrawals have no fee.
Withdrawal limits are configured per channel (daily, weekly, monthly caps), not per entity.
New or modified withdrawal methods have a 48-hour cooling period before they can be used.
Liquidity guards prevent tenants from withdrawing merchant or partner funds.
Once a withdrawal is executing, it cannot be canceled -- only completed or failed.
There are no automatic withdrawals -- the entity must request each one.

Withdrawals

On this page