Merchant Wallet Withdrawals

Definition

Merchant Wallet withdrawals move funds out of the Merchant Wallet (the wallet that receives proceeds from Accepting Payments) to an external destination: another on-chain wallet you control, custody/liquidity, or a payout corridor (handled separately under Payouts).

Note: The Merchant Wallet uses the same underlying wallet construct as Account Wallets in WAAS; it’s labeled “Merchant” in the Accepting Payments context for clarity.

When to Use

Settling sales proceeds to treasury/custody after collection.
Moving funds to liquidity wallets that serve end-user withdrawals.
Funding payout corridors (banks/PSPs) after approval.
Rebalancing across your own wallets or entities.

Execution Modes

Manual (default)

Requests remain pending_review until an authorized approver approves.
Recommended for high-value or first-time destinations.
Provides a clear approval record (who/when/policy version/comments).

Automatic (opt-in)

Executes immediately if balance and policy limits pass.
Configure per-transaction and daily caps suited to your risk profile.
Insufficient funds behavior (choose one per policy):
- Soft fallback: auto-route to Manual review.
- Hard fail: reject with a terminal failure status.

Destination Types

On-chain wallet you control (same asset/rail).
Custody / liquidity destinations.
Payout corridors (PSPs/banks) initiated after a successful withdrawal approval.

Corridor specifics (SEPA, SWIFT, PSPs) are detailed in Payouts: Banks & PSPs.

Validation & Rejections

Address validation: Requests fail if the destination wallet address format/network is invalid or mismatched.
Balance checks: Requests fail or fall back to Manual if available funds are insufficient per policy.
Stale/duplicate requests: Should be rejected by your process based on withdrawalId and latest status.

Typical Flow

Manual

Create request → Pending review → Approve → Execute on-chain → Record result

Automatic

Create request → Policy & balance check → Execute on-chain → Record result

Operational Guidance

Thresholds: Start with conservative caps; raise as operations mature.
First-time destinations: Keep Manual until a destination is verified operationally.
Approver SLAs: Set internal time targets to avoid request backlogs.
Reconciliation: Store on-chain tx IDs, timestamps, amounts, rail (currencyType), destination reference, and approver details (for Manual).

Compliance Notes

Apply sanctions/AML screening to outbound movements in line with your program.
Enforce your restricted-jurisdiction policies.
Ensure internal records clearly map merchant ledger entries to on-chain movements and (if applicable) to downstream payouts.

Best Practices Checklist

Manual by default; enable Automatic only after validating reporting and controls.
Use soft fallback for Automatic to reduce failure rates during scale-up.
Validate destination format/network before approval or execution.
Maintain an audit trail for every withdrawal (request → decision → execution result).
Separate withdrawals (on-chain) from payouts (off-ramp) in your runbooks, even if they are executed back-to-back.