Skip to main content

Overview

When a cardholder swipes their card, the card network sends an authorization webhook to your backend. You have ~2 seconds to check credit, execute an on-chain draw, and respond.
This example uses Rain as the card issuer. Adapt signature validation and response format for your card program.

Implementation

1

Set Up Configuration

2

Define Types and Helpers

3

Handle the Webhook

Delegated Credit Draws

Card authorizations must complete without user interaction. Your backend needs to draw credit on behalf of users. There are two on-chain approaches:

Option A: Non-Custodial (Smart Accounts)

Users deploy a smart account (ERC-4337) and grant your backend a scoped session key or module that can only call the credit draw function. The user retains full custody.

ERC-7579 Session Keys

User grants a scoped session key that can only call the credit draw function. Expires automatically.

Pre-signed Permits

User pre-signs EIP-2612 permits for USDC transfers up to a spending limit.

Smart Account Modules

User’s smart wallet delegates draw authority to your backend via a custom module.

Option B: Operator Contract (Server-Side)

Deploy an ExclusiveOperator contract that lets your backend draw credit on behalf of opted-in users. This is the pattern used by card programs that need server-side control over credit draws. Setup (one-time):
User onboarding:
Drawing credit at swipe time:
Safety guarantees:
  • withdraw() is disabled — the operator can never touch collateral
  • Credit can only go to whitelisted receivers the user has explicitly approved
  • Revocation has a time delay (e.g. 7 days) — prevents users from revoking mid-billing-cycle while the operator still has outstanding credit exposure
  • Users can schedule revocation at any time via revoke(), then finalize after the delay with finalizeRevoke()
The caller address can draw credit from any opted-in user account. Secure the private key with HSM or KMS in production — never store it in environment variables on shared infrastructure.

Latency Budget

Card networks expect a response within ~2 seconds:
Use a dedicated RPC node on Base. Public endpoints will exceed the time budget under load.

Production Checklist

Infrastructure

  • Replace in-memory idempotency map with Redis or database
  • Use a dedicated Base RPC node (Alchemy, QuickNode, or self-hosted)
  • Store signer key in HSM or cloud KMS (AWS KMS, GCP Cloud KMS)
  • Implement getWalletForCard() against your user database
  • Log all authorization decisions for audit trail
  • Load test under expected peak authorization volume
  • Monitor authorization latency (p99 < 2s)
  • Alert on elevated decline rates
  • Track on-chain execution success rate

Environment Variables