Chapter 6: Card Facade

Virtual cards let employees and organizations spend stablecoin balances directly — at merchants, online services, and anywhere Visa is accepted — without a manual off-ramp step. The card facade abstracts card providers behind a common interface, following the same pattern as the fiat ramp facade and the other facades defined in Chapter 1.

Why Cards

The fiat ramp facade solves “convert stablecoins to fiat in a bank account.” Cards solve a different problem: “spend stablecoins as fiat without converting first.”

Without cards, an employee who claims salary in USDC must: initiate an off-ramp → wait for settlement → wait for fiat in their bank → spend from bank. Multiple steps, multiple fees, multiple wait periods between earning and spending.

With cards: claim salary → tap phone at merchant → done. The stablecoin-to-fiat conversion happens at point of sale, invisible to the user.

Employee Cards

Individual cards funded from the employee’s smart account. The employee’s claimed USDC balance is directly spendable.

• Instant spending. No off-ramp settlement delay. Funds are available at the point of sale.
• Online purchases. Pay for goods and services without off-ramping to a bank first.
• Reduced friction. For employees who receive stablecoins but spend in fiat day-to-day, the card eliminates the manual off-ramp step entirely.

Organization Cards

Cards linked to the organization’s Safe treasury, used for business expenses.

• Business expenses. Pay for SaaS tools, office supplies, travel — directly from the Safe’s USDC balance.
• Per-employee limits. The CFO might have a $5,000/month card. A team lead might have $500/month. Each card draws from the same Safe treasury with different spending caps.
• No off-ramp required. Currently, an org must off-ramp from the Safe to a bank account before paying for anything in fiat. Cards eliminate this step.

Revenue

Card transactions generate interchange income — the merchant pays a processing fee (typically 1–3%), and a portion flows back to Capxul as the card program manager. This is a revenue stream that does not exist in the current architecture.

Card Facade Interface

Every card provider must implement:

Card Issuance

• issueCard(userId, fundingModel, cardType) — creates a virtual card. Returns card details (last 4, expiry, CVV for virtual display). cardType is employee or organization.
• getCardDetails(cardId) — retrieves card status, balance (for top-up model), spending limits.
• activateCard(cardId) / freezeCard(cardId) / revokeCard(cardId) — lifecycle management.

Funding

• setFundingSource(cardId, sourceAddress, token, chain) — for non-custodial model. Links the card to a smart account or Safe address.
• approveFunding(cardId, amount) — for non-custodial model. Grants the provider’s smart contract permission to pull funds (via ERC-20 approve()).
• topUp(cardId, amount) — for top-up model. Transfers funds from the smart account to the provider’s card wallet.
• getBalance(cardId) — for top-up model. Returns the card’s available balance.

Spending Limits

• setSpendingLimits(cardId, daily, monthly, perTransaction) — configures caps.
• setMerchantCategories(cardId, allowed, blocked) — optional merchant category restrictions.

Events (Webhooks)

The provider must send webhook events for:

• card.authorization — a transaction is attempted (hold placed)
• card.capture — the transaction is settled (funds debited)
• card.refund — a refund is processed
• card.reversal — an authorization is reversed (hold released)
• card.declined — a transaction was declined (over limit, frozen, etc.)

Geographic Coverage

• getSupportedCountries() — which jurisdictions can cards be issued in.
• getMobileWalletSupport(country) — Apple Pay and Google Pay availability per market.

Funding Models

How the card accesses the user’s stablecoin balance. This is the most important architectural decision for cards.

Non-Custodial (Preferred)

The card provider’s smart contract pulls funds directly from the employee’s smart account (or the org’s Safe) at the point of sale. No separate card balance. No top-up step.

How it works:

1. Employee grants an ERC-20 approve() to the card provider’s smart contract, allowing it to spend USDC from the smart account.
2. Employee taps card at merchant.
3. Provider’s contract calls transferFrom() on the USDC contract, pulling the exact transaction amount from the smart account.
4. Provider converts USDC to fiat and settles with the merchant’s acquiring bank.

Session key implications: The approve() call to the USDC contract must be executable via the employee’s session key. The USDC contract is already on the session key whitelist (it is whitelisted for off-ramp routing). The Convex-side enforcement (Path A) validates that the approve() target is the card provider’s contract and the amount is within configured limits — the same pattern used for off-ramp destination enforcement.

Advantage: Preserves the pull-based architecture. The smart account remains the single source of truth for the employee’s balance. No funds sitting in a separate card wallet.

Constraint: The card provider’s smart contract must be compatible with ERC-4337 smart accounts on Base. Specifically, the approve() and transferFrom() pattern must work when the approving address is a smart contract wallet, not an EOA. This is standard ERC-20 behavior — approve() does not require an EOA — but must be confirmed per provider.

Top-Up (Fallback)

The employee transfers USDC from their smart account to a provider-managed card wallet. The card spends from this separate balance.

How it works:

1. Employee initiates a “top up” — the backend sends USDC from the smart account to the provider’s card wallet address via session key.
2. Provider credits the card balance.
3. Employee spends from the card balance.
4. When the card balance is low, the employee tops up again.

When to use this: If the card provider’s smart contract is not compatible with 4337 accounts, or if the provider does not support non-custodial funding on Base.

Downside: Funds now live in two places (smart account + card wallet). The smart account balance no longer reflects total available funds. The employee must actively manage their card balance. Reconciliation is more complex.

Acceptable for v1 if non-custodial is not available. Users would top up their card the way they top up any prepaid card. Plan to migrate to non-custodial when provider support is confirmed.

Organization Cards — Architecture Outline

Org cards draw from the Safe treasury, not an individual smart account. This introduces different authorization and spending control requirements.

Concept

• Multiple cards per Safe. The CFO, team leads, and authorized employees each get a card with different spending limits.
• All cards draw from the same Safe USDC balance.
• Card spend appears as treasury outflow in the dashboard, alongside stream obligations and invoice payments.

Safe Module Requirements

Org cards require a mechanism that allows the card provider’s contract to pull funds from the Safe within approved limits. This would be a new Zodiac Roles scope (similar to the offramp_backend role defined in the Safe Module Architecture document for fiat off-ramp).

The card module would need to define:

• Per-card spending limits (daily and monthly caps)
• Approved card contract addresses (the card provider’s contract on the Zodiac Roles allowlist)
• A mechanism for Safe signers to freeze or revoke individual cards (a Safe owner transaction that revokes the approval)

Caution

The Safe card module is not yet designed. The concept is sound — it follows the same Zodiac Roles pattern used for the Payment Module and off-ramp backend role — but the specific scoping rules, limit enforcement mechanism, and multi-card management interface are open questions. See Open Questions for the specific items to resolve.

Reconciliation

Card transactions produce records in the Financial Document Layer. Each card swipe generates a card.authorization event via webhook, followed by card.capture when settled. These events create or update records in Convex. Card spend appears as an outflow in treasury reporting — burn rate calculations must include card spend alongside stream obligations and invoice payments.

Card Provider Registry

The cardProviders table in Convex follows the standard provider registry pattern defined in Chapter 1:

• Provider ID, name, active flag
• Supported countries (where cards can be issued)
• Supported funding models (non_custodial, top_up, or both)
• Supported card types (employee, organization, or both)
• Mobile wallet support per country (Apple Pay, Google Pay)
• Card network (Visa, Mastercard)
• Card contract address (for non-custodial funding — the address that needs approve())
• Webhook endpoint configuration

At launch: the registry may have one provider. The facade supports multiple providers routed by geography, following the multi-provider routing pattern from Chapter 1.

Integration Points

Session Keys (Employee Cards)

The card provider’s contract address is added to the session key whitelist alongside the USDC contract and LlamaPay. This is a new scope — the employee grants card spend authorization separately from off-ramp authorization. See Chapter 3 for the session key model.

Financial Document Layer

Card transactions are a new financial event type in the Financial Document Layer (Chapter 8). Card spend records include: transaction amount, merchant info, card ID (last 4), timestamp, status (authorized → captured → settled), and interchange revenue (if applicable). These records link to treasury outflow calculations for org cards and personal spend tracking for employee cards.

Event Indexing

Card events arrive via webhooks, not on-chain events. The webhook processing pipeline (same pattern as fiat ramp webhooks in Chapter 5) receives card events, validates signatures, parses via the provider adapter, and creates or updates records in Convex.

Identity Verification

Card issuance may require additional KYC beyond what Capxul collects via Shufti Pro. This depends on the card provider’s requirements and whether the provider accepts Capxul’s verification attestation. See Chapter 11 for the verification facade and the attestation passthrough pattern.

Current Provider Evaluation

Bridge (Stripe subsidiary) is the first card provider evaluated. See Appendix D: Bridge Platform Evaluation for the full assessment, including 4337 compatibility questions, market availability in target countries, and the evaluation rubric.

No card provider is active at launch. The Card Facade and provider registry are designed now so that activating a card provider is a configuration change, not a platform rewrite.