> ## Documentation Index > Fetch the complete documentation index at: https://docs.sumvin.com/llms.txt > Use this file to discover all available pages before exploring further. # Receive an issuer card-tokenization webhook > Receives a signed webhook from the card issuer carrying raw card material for a card the server already owns, then tokenizes that material in-flight and persists only the resulting reference ids. No card number or security code is ever persisted or logged. **Signature scheme:** Each request carries two headers that must both be present: - `card-issuer-signature` — base64url-encoded HMAC-SHA256 over the canonical string `"{timestamp}.{url}.{body}"`, signed with the configured issuer webhook secret. - `card-issuer-signature-timestamp` — unix epoch seconds at which the issuer signed the request. **Timestamp tolerance:** Requests with a timestamp more than 300 seconds from server time are rejected before HMAC compute, in either direction. **Failure modes:** A missing or invalid signature returns `401` with error code `CRD-401-001`. The detail is a fixed string and never echoes the client-supplied signature or timestamp. Successful delivery returns `200`; replays of the same `eventId` are accepted as `200` no-ops so the issuer's retries are safe. Handler exceptions surface as `5xx` so the issuer will retry. ## OpenAPI ````yaml /api-reference/openapi.json post /v0/webhooks/card-issuer/tokenize openapi: 3.1.0 info: title: Sumvin API version: 0.35.2 servers: - url: https://api.sumvin.com description: Production security: [] tags: - name: User description: > User identity and account management for the Sumvin platform. ## Capabilities - **Account Creation** - Register new users with automatic primary wallet setup - **Profile Management** - Retrieve and update user profile information - **Phone Verification** - Two-step phone verification with SMS codes - **Resource Expansion** - Fetch related resources (wallets, status_history) in a single request ## Authentication All endpoints require a valid JWT passed in the `x-juno-jwt` header: ``` x-juno-jwt: ``` Two JWT issuers are supported by the platform's auth layer: | Issuer | Status | |--------|--------| | **Dynamic Labs** | Currently active. JWTs are validated against the configured Dynamic Labs environment. | | **Privy** | Supported by the platform's auth layer; provisioning the issuer for a given environment is a deployment-config step. Contact the team for sandbox or production credentials. | Both issuer types are accepted simultaneously when configured. Identify which provider issued a given JWT via the `auth_provider` field on the user response (`dynamic` or `privy`). ## User Lifecycle ``` ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ Register │────►│ Verify KYC │────►│ Active │ │ (pending) │ │(in_progress)│ │ │ └─────────────┘ └─────────────┘ └─────────────┘ │ ┌─────┴─────┐ ▼ ▼ ┌───────────┐ ┌───────────┐ │ Retry │ │ Rejected │ │(needs fix)│ │ (terminal)│ └─────┬─────┘ └───────────┘ │ └──► Resubmit → Review → Active ``` ## Key Concepts | Concept | Description | |---------|-------------| | `id` | Public user identifier (format: `usr_xxx`) for API references | | `auth_provider_id` | User's ID from the authentication provider (Dynamic Labs or Privy) | | `primary_eoa_address` | User's main externally-owned wallet address | | `safe_creation_status` | Async Safe wallet deployment: `processing`, `completed`, `failed` | ## Expand Parameters Use `?expand=` to include related resources: | Parameter | Description | |-----------|-------------| | `wallets` | Include all user wallets | | `status_history` | Include full audit trail of account status changes | ## Related Resources - [KYC](#tag/KYC) - Identity verification - [Wallets](#tag/Wallets) - Wallet management - name: KYC description: > Know Your Customer (KYC) identity verification via Sumsub integration. ## Capabilities - **SDK Token Generation** - Create short-lived tokens for Sumsub Web SDK - **Status Tracking** - Monitor verification progress and results - **Document Verification** - Track submitted documents and their status - **GDPR Compliance** - Access verification details with privacy-safe filtering ## Verification Flow ``` ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ Generate SDK │────►│ User does │────►│ Webhook │ │ Token │ │ verification │ │ received │ └──────────────┘ │ in Sumsub │ └──────────────┘ └──────────────┘ │ ▼ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ approved │◄────│ Review │◄────│ Processing │ │ │ │ (if needed) │ │ │ └──────────────┘ └──────┬───────┘ └──────────────┘ │ │ │ ┌─────┴─────┐ │ ▼ ▼ │ ┌───────────┐ ┌───────────┐ │ │ retry │ │ rejected │ │ │ (fixable) │ │ (terminal)│ │ └─────┬─────┘ └───────────┘ │ │ │ └──► Resubmit → Review ▼ ┌──────────────┐ │ User active │ │ Full access │ └──────────────┘ ``` ## Verification Statuses | Status | Description | |--------|-------------| | `pending` | KYC not started | | `in_progress` | Documents submitted, awaiting review | | `retry` | Additional documents or corrections needed - user CAN resubmit | | `approved` | Identity verified successfully | | `rejected` | Verification failed permanently - user CANNOT retry | ## SDK Integration 1. Call `POST /v0/kyc/access-token` to get a token 2. Initialize Sumsub Web SDK with the token 3. User completes verification in SDK 4. Poll `GET /v0/kyc/status` or listen for webhooks ## Related Resources - [User](#tag/User) - User profile management - [Webhooks](#tag/Webhooks) - KYC status change notifications - name: Wallets description: > Multi-chain wallet management supporting EOA and Safe multisig wallets. ## Capabilities - **Multi-Chain Support** - Manage wallets across Ethereum, Base, Polygon, and more - **Wallet Types** - EOA (externally owned) and Safe smart wallets - **Primary Designation** - Set primary wallet per type for default transactions - **Soft Delete** - Remove wallets while preserving transaction history ## Wallet Types | Type | Description | |------|-------------| | **EOA** | Standard Ethereum wallet controlled by private key | | **Safe** | Gnosis Safe multisig with agent key as signer | ## Creation Flow ``` ┌─────────────────┐ │ User registers │ └────────┬────────┘ │ ▼ ┌─────────────────┐ ┌─────────────────┐ │ Primary EOA set │────►│ Safe deployment │ │ immediately │ │ triggered │ └─────────────────┘ └────────┬────────┘ │ ┌────────┴────────┐ ▼ ▼ ┌──────────────┐ ┌──────────────┐ │ completed │ │ failed │ │ Safe address │ │ Retry via │ │ stored │ │ PATCH wallet│ └──────────────┘ └──────────────┘ ``` ## Primary Wallet Rules - One primary EOA and one primary Safe per user - Primary EOA and Safe must be on the same chain (`primary_chain_id`) - Changing primary wallet may trigger new Safe deployment (returns 202) ## Key Concepts | Concept | Description | |---------|-------------| | `chain_id` | EIP-155 chain identifier (e.g., 1=Ethereum, 8453=Base) | | `is_primary` | Whether this is the default wallet for its type | | `safe_creation_event_id` | Event ID for tracking async Safe deployment | | `nickname` | User-defined friendly name for the wallet | ## Filtering ``` GET /v0/wallets?chain_id=8453&is_eoa=true ``` | Parameter | Description | |-----------|-------------| | `chain_id` | Filter by blockchain | | `is_eoa` | Filter by wallet type (true=EOA, false=Safe) | ## Related Resources - [Wallet Assets](#tag/Wallet-Assets) - Asset balances per wallet - [Assets](#tag/Assets) - Supported currencies and tokens - [Transactions](#tag/Transactions) - Wallet transaction history - name: Wallet Assets description: | Asset balances and holdings within user wallets. ## Capabilities - **Balance Tracking** - Real-time asset balances per wallet - **Multi-Asset Support** - Native tokens, ERC-20s, and fiat equivalents - **Chain-Specific Data** - Balances scoped to specific blockchains ## Response Structure ```json { "wallet_id": 123, "assets": [ { "asset": { "symbol": "ETH", "name": "Ethereum", ... }, "balance": "1.5", "value_usd": "2734.50" } ], "_links": { ... } } ``` ## Key Concepts | Concept | Description | |---------|-------------| | `balance` | Raw balance in asset's base units (string for precision) | | `value_usd` | USD equivalent at current market price | | `decimals` | Asset's decimal precision for display formatting | ## Related Resources - [Wallets](#tag/Wallets) - Wallet management - [Assets](#tag/Assets) - Asset metadata and pricing - name: Assets description: > Supported currencies, tokens, and their market data. ## Capabilities - **Asset Registry** - All supported crypto and fiat currencies - **Price Feeds** - Current market prices with timestamps - **Metadata** - Symbol, name, decimals, contract addresses ## Asset Types | Type | Description | Examples | |------|-------------|----------| | `crypto` | Blockchain-native tokens | ETH, USDC, MATIC | | `fiat` | Traditional currencies | USD, EUR, GBP | ## Decimal Handling All amounts use string representation to preserve precision: | Asset | Decimals | Example | |-------|----------|---------| | ETH | 18 | `"1.500000000000000000"` | | USDC | 6 | `"100.000000"` | | USD | 2 | `"100.00"` | ## Filtering ``` GET /v0/assets?asset_type=crypto&chain_id=8453 ``` | Parameter | Description | |-----------|-------------| | `asset_type` | Filter by `crypto` or `fiat` | | `chain_id` | Filter by blockchain (crypto only) | | `symbol` | Search by ticker symbol | ## Related Resources - [Wallets](#tag/Wallets) - Wallet management - [Wallet Assets](#tag/Wallet-Assets) - Per-wallet balances - [Transactions](#tag/Transactions) - Transaction amounts use asset decimals - name: Bank Accounts description: > Linked bank account management for fiat on/off ramps. ## Capabilities - **Account Linking** - Connect external bank accounts via Open Banking - **Balance Access** - View linked account balances (where permitted) - **Transfer Support** - Enable bank-to-wallet and wallet-to-bank transfers ## Linking Flow ``` ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ Initiate link │────►│ Open Banking │────►│ Account(s) │ │ │ │ OAuth consent │ │ linked │ └─────────────────┘ └─────────────────┘ └─────────────────┘ ``` ## Key Concepts | Concept | Description | |---------|-------------| | `institution_id` | Bank identifier from Open Banking provider | | `account_type` | Checking, savings, etc. | | `currency` | Account's native currency | ## Related Resources - [Open Banking](#tag/Open-Banking) - Institution connections - [Accounts](#tag/Accounts) - Unified account view - [Transactions](#tag/Transactions) - Bank transaction history - name: Accounts description: | Unified financial account aggregation across all sources. ## Capabilities - **Account Aggregation** - View all financial accounts in one place - **Balance Tracking** - Current balances across account types - **Source Attribution** - Distinguish crypto, bank, and card accounts ## Account Sources | Source | Description | |--------|-------------| | `crypto_wallet` | Blockchain wallets (EOA, Safe) | | `bank_account` | Linked bank accounts | | `card` | Sumvin virtual cards | ## Related Resources - [Wallets](#tag/Wallets) - Crypto wallet details - [Bank Accounts](#tag/Bank-Accounts) - Bank account details - [Cards](#tag/Cards) - Card account details - name: Open Banking description: > Open Banking institution connections and OAuth flows. ## Capabilities - **Institution Discovery** - Search supported banks and financial institutions - **OAuth Integration** - Secure account linking via bank's consent flow - **Connection Management** - View and revoke institution connections ## Connection Flow ``` ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ Get link URL │────►│ User consent │────►│ Callback │ │ │ │ at bank site │ │ with code │ └─────────────────┘ └─────────────────┘ └────────┬────────┘ │ ▼ ┌─────────────────┐ │ Accounts synced │ └─────────────────┘ ``` ## Related Resources - [Bank Accounts](#tag/Bank-Accounts) - Linked account management - [Accounts](#tag/Accounts) - Unified account view - name: Cards description: > Virtual card issuance and lifecycle management. ## Capabilities - **Card Issuance** - Create virtual Visa/Mastercard cards - **Lifecycle Management** - Activate, freeze, unfreeze, and close cards - **Spending Controls** - Set transaction limits and merchant restrictions - **Card Details** - Retrieve PAN, CVV, expiry for payments ## Card States ``` ┌──────────┐ ┌──────────┐ ┌───────────┐ │ pending │────►│ active │────►│ suspended │ │ │ │ │◄────│ │ └──────────┘ └────┬─────┘ └───────────┘ │ ▼ ┌──────────┐ │ closed │ (terminal) └──────────┘ ``` ## Card Types | Type | Description | |------|-------------| | `virtual` | Digital-only card for online payments | | `physical` | Physical card (future support) | ## Spending Controls | Control | Description | |---------|-------------| | `daily_limit` | Maximum spend per day | | `monthly_limit` | Maximum spend per month | | `single_transaction_limit` | Maximum per transaction | | `allowed_mcc` | Allowed merchant category codes | | `blocked_mcc` | Blocked merchant category codes | ## Sensitive Data Card details (PAN, CVV) are returned only via dedicated secure endpoints with additional authentication. ## Related Resources - [Card Funding](#tag/Card-Funding) - Load funds to cards - [Transactions](#tag/Transactions) - Card transaction history - [Wallets](#tag/Wallets) - Funding source wallets - name: Card Funding description: | Fund virtual cards from crypto wallets or bank accounts. ## Capabilities - **Crypto Funding** - Load cards directly from crypto wallets - **Bank Funding** - Load cards from linked bank accounts - **Instant Loading** - Real-time balance updates ## Funding Flow ``` ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ Select source │────►│ Confirm USD │────►│ Card balance │ │ wallet/bank │ │ amount │ │ updated │ └─────────────────┘ └─────────────────┘ └─────────────────┘ ``` ## Funding Sources | Source | Description | |--------|-------------| | `crypto_wallet` | Convert crypto to USD and load | | `bank_account` | ACH transfer from linked bank | ## Related Resources - [Cards](#tag/Cards) - Card management - [Wallets](#tag/Wallets) - Crypto funding sources - [Bank Accounts](#tag/Bank-Accounts) - Bank funding sources - name: Transactions description: > Unified transaction history across all financial sources. ## Capabilities - **Multi-Source History** - Crypto, card, and bank transactions in one feed - **Rich Filtering** - Filter by type, status, date, amount, category - **Metadata Aggregation** - Cashflow summaries and category breakdowns - **Pagination** - Efficient access to large transaction histories ## Transaction Types | Type | Description | |------|-------------| | `deposit` | Funds received | | `withdrawal` | Funds sent out | | `transfer` | Internal transfer between accounts | | `swap` | Crypto-to-crypto exchange | | `card_purchase` | Card payment at merchant | | `card_refund` | Merchant refund to card | | `on_ramp` | Fiat to crypto conversion | | `off_ramp` | Crypto to fiat conversion | | `bank_transfer` | Bank account transfer | | `direct_debit` | Recurring bank debit | | `standing_order` | Scheduled bank payment | | `bank_payment` | Outgoing bank payment | | `bank_refund` | Bank payment reversal | | `interest` | Interest earned | | `fee` | Service fee | ## Transaction Lifecycle ``` ┌──────────┐ ┌──────────┐ ┌──────────┐ │ pending │────►│processing│────►│completed │ └──────────┘ └────┬─────┘ └──────────┘ │ ▼ ┌──────────┐ │ failed │ └──────────┘ ``` ## Filtering & Pagination ``` GET /v0/transactions?type=card_purchase&status=completed&limit=50&offset=0 ``` | Parameter | Description | |-----------|-------------| | `type` | Transaction type filter | | `status` | Status filter | | `direction` | `in` or `out` | | `wallet_id` | Filter by wallet | | `card_id` | Filter by card | | `period_start` | Start date (epoch ms) | | `period_end` | End date (epoch ms) | | `amount_min` | Minimum amount | | `amount_max` | Maximum amount | | `category` | Spending category | ## Metadata Aggregation Add `?meta=true` to include: ```json { "meta": { "transaction_count": 150, "date_range": { "earliest": "...", "latest": "..." }, "cashflow": { "gross_in": "5000.00", "gross_out": "3200.00", "net": "1800.00" }, "categories": [ { "category": "restaurants", "total_amount": "450.00", "percentage_of_total": 14.1 } ] } } ``` ## Related Resources - [Wallets](#tag/Wallets) - Crypto transaction sources - [Cards](#tag/Cards) - Card transaction sources - [Budgets](#tag/Budgets) - Category-based spending limits - [Assets](#tag/Assets) - Transaction asset details - name: Budgets description: > Category-based spending budgets and tracking. ## Capabilities - **Category Budgets** - Set spending limits by category - **Period Tracking** - Weekly, monthly, or custom periods - **Progress Monitoring** - Track spending against budget limits - **Overspend Alerts** - Notifications when approaching or exceeding limits ## Budget Structure ```json { "id": 123, "category": "restaurants", "amount": "500.00", "currency": "USD", "period": "monthly", "spent": "342.50", "remaining": "157.50", "percentage_used": 68.5 } ``` ## Periods | Period | Description | |--------|-------------| | `weekly` | Resets every Monday | | `monthly` | Resets on the 1st | | `custom` | User-defined start/end dates | ## Categories Standard spending categories: | Category | Description | |----------|-------------| | `restaurants` | Dining and food delivery | | `groceries` | Supermarkets and food stores | | `transportation` | Rideshare, gas, public transit | | `entertainment` | Movies, games, streaming | | `shopping` | Retail and online shopping | | `utilities` | Bills and subscriptions | | `travel` | Hotels, flights, vacation | | `health` | Medical, pharmacy, fitness | | `other` | Uncategorized spending | ## Related Resources - [Transactions](#tag/Transactions) - Transaction categorization - [Insights](#tag/Insights) - Spending analysis and recommendations - name: Insights description: | AI-powered financial insights and spending analysis. ## Capabilities - **Spending Analysis** - Identify patterns and trends in spending - **Anomaly Detection** - Flag unusual transactions - **Recommendations** - Actionable suggestions for saving money - **Periodic Reports** - Weekly and monthly financial summaries ## Insight Types | Type | Description | |------|-------------| | `spending_spike` | Unusual increase in category spending | | `recurring_charge` | Detected subscription or recurring payment | | `saving_opportunity` | Potential way to reduce spending | | `budget_warning` | Approaching or exceeded budget | | `goal_progress` | Progress toward financial goals | ## Related Resources - [Transactions](#tag/Transactions) - Transaction data for analysis - [Budgets](#tag/Budgets) - Budget status insights - [Strategies](#tag/Strategies) - Automated responses to insights - name: Strategies description: > Available automation templates for financial management. ## Capabilities - **Strategy Catalog** - Browse available automation templates - **Parameter Definitions** - Understand required configuration - **Category Browsing** - Find strategies by use case ## Strategy Categories | Category | Description | Examples | |----------|-------------|----------| | `savings` | Automatic saving rules | Round-up, percentage save | | `investing` | Automated investing | DCA, rebalancing | | `spending` | Spending controls | Category limits, merchant blocks | | `alerts` | Notification triggers | Large transaction, low balance | ## Related Resources - [User Strategies](#tag/User-Strategies) - Configure strategies for your account - [Agent Tasks](#tag/Agent-Tasks) - View execution history - name: User Strategies description: | User-configured automation strategies. ## Capabilities - **Strategy Configuration** - Set up strategies with custom parameters - **Enable/Disable** - Toggle strategies without deleting configuration - **Parameter Updates** - Modify strategy settings ## Configuration Flow ``` ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ Browse catalog │────►│ Configure │────►│ Enable & │ │ (Strategies) │ │ parameters │ │ start running │ └─────────────────┘ └─────────────────┘ └─────────────────┘ ``` ## Strategy States | State | Description | |-------|-------------| | `enabled` | Actively running | | `disabled` | Configured but paused | | `error` | Failed, needs attention | ## Related Resources - [Strategies](#tag/Strategies) - Available templates - [Agent Tasks](#tag/Agent-Tasks) - Execution history - name: Agent Tasks description: | Agent task execution history and results. ## Capabilities - **Execution History** - View all agent tasks - **Task Details** - See inputs, outputs, and any errors - **Manual Triggers** - Force immediate strategy execution - **Filtering** - Find tasks by strategy, status, or date ## Task Lifecycle ``` ┌────────┐ ┌────────┐ ┌─────────┐ ┌──────────┐ │ queued │────►│ next │────►│ running │────►│ completed│ └────────┘ └────────┘ └────┬────┘ └──────────┘ │ ┌───────────┼───────────┐ ▼ ▼ ┌──────────┐ ┌───────────┐ │ failed │ │ cancelled │ └──────────┘ └───────────┘ ``` ## Task Statuses | Status | Description | |--------|-------------| | `queued` | Created, waiting to be scheduled | | `next` | Promoted to next slot, about to run | | `running` | Currently executing | | `completed` | Finished successfully | | `failed` | Encountered an error | | `cancelled` | Cancelled before completion | ## Related Resources - [User Strategies](#tag/User-Strategies) - Strategy configuration - [Strategies](#tag/Strategies) - Strategy definitions - name: Chat description: | Conversational AI interface for financial management. ## Capabilities - **Natural Language** - Interact with your finances conversationally - **Session Management** - Maintain conversation context - **Tool Integration** - AI can execute actions on your behalf - **History Access** - Review past conversations ## Session Flow ``` ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ Create session │────►│ Send messages │────►│ AI responds │ │ │ │ │◄────│ (may use tools)│ └─────────────────┘ └─────────────────┘ └─────────────────┘ ``` ## Message Types | Type | Description | |------|-------------| | `user` | Message from the user | | `assistant` | Response from AI | | `tool_call` | AI requesting to execute an action | | `tool_result` | Result of tool execution | ## Related Resources - [Agent](#tag/Agent) - Agent authentication - [Widgets](#tag/Widgets) - Embeddable chat components - name: Widgets description: | Embeddable UI components for external integration. ## Capabilities - **Widget Configuration** - Customize appearance and behavior - **Embed Codes** - Get HTML/JS snippets for embedding - **Data Binding** - Connect widgets to user data ## Widget Types | Type | Description | |------|-------------| | `balance` | Display account balances | | `transactions` | Transaction list or feed | | `chat` | Conversational interface | | `budget` | Budget progress visualization | ## Related Resources - [Chat](#tag/Chat) - Chat widget backend - [Transactions](#tag/Transactions) - Transaction widget data - name: Connectors description: > Available external service integrations. ## Capabilities - **Connector Catalog** - Browse available integrations - **Capability Discovery** - Understand what each connector provides - **Authentication Requirements** - Know what's needed to connect ## Connector Types | Type | Description | |------|-------------| | `exchange` | Crypto exchanges (Coinbase, Binance) | | `bank` | Banking integrations | | `accounting` | Accounting software | | `tax` | Tax reporting services | ## Related Resources - [User Connectors](#tag/User-Connectors) - Connect services to your account - name: User Connectors description: | User's active external service connections. ## Capabilities - **Connection Management** - Add and remove integrations - **OAuth Flows** - Secure authorization with external services - **Sync Status** - Monitor data synchronization - **Credential Updates** - Refresh expired authorizations ## Connection Flow ``` ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ Select connector│────►│ OAuth flow │────►│ Connected & │ │ from catalog │ │ with service │ │ syncing │ └─────────────────┘ └─────────────────┘ └─────────────────┘ ``` ## Connection States | State | Description | |-------|-------------| | `connected` | Active and syncing | | `disconnected` | Removed by user | | `error` | Authorization expired or failed | ## Related Resources - [Connectors](#tag/Connectors) - Available integrations - name: User Rules description: | Custom automation rules with trigger conditions. ## Capabilities - **Rule Creation** - Define custom automation logic - **Trigger Conditions** - Set when rules should execute - **Action Configuration** - Define what happens when triggered - **Rule Management** - Enable, disable, and edit rules ## Rule Structure ``` WHEN [trigger condition] THEN [action] ``` ## Trigger Types | Trigger | Description | |---------|-------------| | `transaction_received` | New incoming transaction | | `balance_threshold` | Balance crosses amount | | `time_based` | Scheduled execution | | `price_alert` | Asset price condition | ## Action Types | Action | Description | |--------|-------------| | `transfer` | Move funds between accounts | | `notification` | Send alert to user | | `strategy_trigger` | Execute a strategy | ## Related Resources - [Strategies](#tag/Strategies) - Pre-built automation templates - [User Strategies](#tag/User-Strategies) - Active automations - name: Agent description: | Agent authentication tokens for AI-powered operations. ## Capabilities - **Token Generation** - Create scoped access tokens for agents - **Scope Control** - Limit agent capabilities - **Token Rotation** - Refresh tokens securely ## Token Scopes | Scope | Description | |-------|-------------| | `read:transactions` | View transaction history | | `read:balances` | View account balances | | `write:transfers` | Execute transfers | | `write:strategies` | Manage strategies | ## Usage Include agent token in requests: ``` x-sumvin-token: ``` ## Related Resources - [Chat](#tag/Chat) - Conversational AI interface - [Strategies](#tag/Strategies) - Agent-executable automations - name: Webhooks description: > Incoming webhook handlers for third-party provider integrations. ## Overview These endpoints receive event notifications FROM external providers (Sumsub, Meld) and process them to update user state. They are NOT for developers to subscribe to - they are internal integration endpoints. ## Supported Providers | Provider | Endpoint | Purpose | |----------|----------|---------| | **Sumsub** | `POST /v0/webhooks/kyc/sumsub/events` | KYC verification status updates | | **Meld** | `POST /v0/webhooks/meld/events` | Bank-linking and crypto on/off-ramp events | ## Sumsub Webhook Events KYC status changes are received from Sumsub and update user verification status: | Sumsub Event | Result | |--------------|--------| | `applicantReviewed` (GREEN) | User approved, status → `approved` | | `applicantReviewed` (RED) | User rejected, status → `rejected` | | `applicantPending` | Additional review needed, status → `retry` | ## Security Both endpoints validate incoming requests using provider-specific signature verification before processing. ## Future: Outgoing Webhooks Developer-facing outgoing webhooks (event subscriptions for your applications) are planned but not yet implemented. ## Related Resources - [KYC](#tag/KYC) - KYC verification flow - [Open Banking](#tag/Open-Banking) - Bank connection management - name: Health description: | System health checks and service status. ## Capabilities - **Liveness Check** - Verify API is responding - **Readiness Check** - Verify all dependencies are available - **Service Status** - Individual component health ## Endpoints | Endpoint | Purpose | |----------|---------| | `GET /health` | Quick liveness check (returns 200 if alive) | ## Response Codes | Code | Meaning | |------|---------| | `200` | Service healthy and ready | | `503` | Service degraded or dependencies unavailable | ## Usage Use for: - Load balancer health checks - Kubernetes liveness/readiness probes - Monitoring and alerting - name: AgentTool description: > Endpoints designed for AI agent consumption. ## Overview Endpoints tagged with `AgentTool` are optimized for programmatic access by AI agents. They typically: - Return structured data suitable for LLM processing - Include clear field descriptions - Support filtering for focused queries - Are read-heavy (prefer GET operations) ## Usage Pattern AI agents should: 1. Authenticate with an agent token (see [Agent](#tag/Agent)) 2. Use these endpoints to gather information 3. Present findings to users or execute follow-up actions ## Available Operations AgentTool-tagged operations span multiple resources: - **Wallets** - List and retrieve wallet details - **Transactions** - Query transaction history - **Cards** - Card information and management - **Budgets** - Budget status and tracking - **Accounts** - Account balances and details - **Agent Tasks** - Automation execution status ## Related Resources - [Agent](#tag/Agent) - Token management for agents - [Chat](#tag/Chat) - Conversational interface using these tools paths: /v0/webhooks/card-issuer/tokenize: post: tags: - Webhooks summary: Receive an issuer card-tokenization webhook description: >- Receives a signed webhook from the card issuer carrying raw card material for a card the server already owns, then tokenizes that material in-flight and persists only the resulting reference ids. No card number or security code is ever persisted or logged. **Signature scheme:** Each request carries two headers that must both be present: - `card-issuer-signature` — base64url-encoded HMAC-SHA256 over the canonical string `"{timestamp}.{url}.{body}"`, signed with the configured issuer webhook secret. - `card-issuer-signature-timestamp` — unix epoch seconds at which the issuer signed the request. **Timestamp tolerance:** Requests with a timestamp more than 300 seconds from server time are rejected before HMAC compute, in either direction. **Failure modes:** A missing or invalid signature returns `401` with error code `CRD-401-001`. The detail is a fixed string and never echoes the client-supplied signature or timestamp. Successful delivery returns `200`; replays of the same `eventId` are accepted as `200` no-ops so the issuer's retries are safe. Handler exceptions surface as `5xx` so the issuer will retry. operationId: handle_card_issuer_webhook_v0_webhooks_card_issuer_tokenize_post parameters: - name: card-issuer-signature in: header required: false schema: anyOf: - type: string - type: 'null' title: Card-Issuer-Signature - name: card-issuer-signature-timestamp in: header required: false schema: anyOf: - type: string - type: 'null' title: Card-Issuer-Signature-Timestamp - $ref: '#/components/parameters/XTimestampFormat' requestBody: required: true content: application/json: schema: title: CardIssuerWebhookPayload type: object required: - eventId - cardExternalId - card properties: eventId: type: string description: >- Unique identifier for the webhook delivery, used for replay dedup. cardExternalId: type: string description: >- Server-owned reference identifying the card the material belongs to. card: type: object required: - number - expirationMonth - expirationYear - securityCode properties: number: type: string description: Card primary account number. expirationMonth: type: string description: Two-digit expiry month. expirationYear: type: string description: Four-digit expiry year. securityCode: type: string description: Card security code. responses: '200': description: Webhook received content: application/json: schema: $ref: '#/components/schemas/CardIssuerWebhookAck' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ProblemDetail' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' components: parameters: XTimestampFormat: name: X-Timestamp-Format in: header required: false description: >- Controls how timestamp fields are serialized in JSON response bodies. **Default (header omitted or any other value):** epoch milliseconds as integers. **`iso8601`:** UTC ISO 8601 strings of the form `YYYY-MM-DDTHH:MM:SSZ`. Example: with `X-Timestamp-Format: iso8601`, the field value `1704067200000` becomes `"2024-01-01T00:00:00Z"`. Affected fields (recursively, in dicts and arrays): any field whose name ends in `_at`, plus the literal field names `timestamp`, `period_start`, and `period_end`. All other fields are passed through unchanged. Only `iso8601` is recognized. Any other value (or omitting the header) yields the default epoch-ms representation; the server does not reject unknown values, so this is documented as an example rather than an enum to keep generated clients permissive. schema: type: string example: iso8601 example: iso8601 schemas: CardIssuerWebhookAck: properties: received: type: boolean title: Received default: true type: object title: CardIssuerWebhookAck description: >- Acknowledgement returned for every accepted webhook delivery (incl. no-op replays). ProblemDetail: properties: type: type: string title: Type description: >- URI reference identifying the problem type. Format: https://api.sumvin.com/errors/{error_code} title: type: string title: Title description: >- Short, human-readable summary of the problem type. Does not change between occurrences. status: type: integer title: Status description: HTTP status code for this error response. detail: type: string title: Detail description: >- Human-readable explanation specific to this occurrence of the problem. instance: type: string title: Instance description: >- URI reference identifying the specific occurrence (typically the request path). error_code: $ref: '#/components/schemas/APIErrorCode' description: >- Machine-readable error code for programmatic handling. Format: {DOMAIN}-{STATUS}-{SEQUENCE} trace_id: anyOf: - type: string - type: 'null' title: Trace Id description: >- Correlation ID for tracing this request. Include when contacting support. type: object required: - type - title - status - detail - instance - error_code title: ProblemDetail description: >- RFC 7807 Problem Details response for API errors. All error responses follow this standard format, enabling consistent error handling across different clients. The `error_code` field provides a machine-readable identifier for programmatic error handling, while `detail` provides human-readable context. Error codes follow the pattern `{DOMAIN}-{HTTP_STATUS}-{SEQUENCE}`. Domain prefixes in use today: ACC (account), AGT (agent token), ALC (Alchemy webhook), AST (asset), BNK (bank), BUD (budget), CALLER (request credentials), CHA (chat attachment), CHT (chat session), CLI (command-line sign-in & personal access tokens), CON (connector), CRD (card), DMO (Visa checkout demo), DYN (Dynamic credential), FAC (facilitator), GATE (feature gate), GEN (general validation), HEALTH (health check), IDT (identity token), INS (insight), IPA (intelligent purchase authorization), KYC (KYC/verification), MLD (MELD), MRC (merchant search), OBK (open banking), ONB (onboarding), ORG (organisation), PAY (payment link), PFP (profile picture), PHONE (phone verification), PINT (payment intent token), PRV (provider), RCT (receipt), RMP (ramp), RPC (RPC usage), RUL (rule), RUN (strategy run), SAF (Safe smart contract), SGN (signer setup), SIS (Sumvin Integration Services), SIW (Sign-In With Ethereum), SRI (Sumvin Resource Identifier), STR (strategy), STS (user status), SYS (system), TAP (Trusted Agent Protocol), TOL (tool), TXN (transaction), UCO (user connector), USR (user), UST (user strategy), VIC (Visa checkout), WAL (wallet), WID (widget). See the Error Reference section for a complete list of error codes and recovery actions. example: detail: No wallet found with ID 12345 for this user. error_code: WAL-404-001 instance: /v0/wallets/12345 status: 404 title: Wallet Not Found trace_id: abc123-def456-ghi789 type: https://api.sumvin.com/errors/wal-404-001 HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError APIErrorCode: type: string enum: - USR-208-001 - USR-404-001 - USR-401-001 - USR-401-002 - USR-400-001 - USR-424-001 - USR-409-002 - USR-400-002 - USR-404-002 - USR-429-001 - PFP-400-001 - PFP-400-002 - PFP-500-001 - PFP-500-002 - PFP-404-001 - PFP-429-001 - WAL-404-001 - WAL-409-001 - WAL-403-001 - WAL-403-002 - WAL-400-001 - WAL-400-002 - WAL-403-003 - WAL-403-004 - WAL-400-003 - WAL-400-004 - WAL-400-005 - WAL-400-006 - WAL-400-007 - WAL-409-002 - KYC-400-001 - KYC-400-002 - KYC-500-001 - KYC-403-001 - KYC-403-002 - KYC-401-001 - KYC-500-002 - KYC-502-001 - KYC-404-001 - KYC-500-003 - KYC-500-004 - KYC-409-001 - KYC-502-002 - KYC-401-002 - KYC-502-003 - KYC-400-003 - KYC-409-002 - KYC-501-001 - KYC-502-004 - KYC-400-004 - KYC-409-003 - KYC-409-004 - KYC-404-002 - KYC-409-005 - KYC-409-006 - KYC-403-003 - KYC-410-001 - KYC-429-001 - KYC-503-001 - KYC-422-001 - SAF-202-001 - SAF-500-001 - SAF-502-001 - SAF-400-001 - SAF-400-002 - SAF-404-001 - SAF-424-001 - SAF-403-001 - SAF-400-003 - SAF-429-001 - SAF-404-002 - SAF-404-003 - SAF-424-002 - SAF-424-003 - SAF-424-004 - IDT-424-001 - SAF-400-004 - SAF-400-005 - SAF-502-002 - SAF-502-003 - SAF-502-004 - SAF-502-005 - SAF-409-001 - SAF-503-005 - SAF-400-006 - SAF-400-007 - SAF-400-008 - SAF-502-006 - SAF-400-009 - SAF-400-010 - SAF-400-011 - SAF-400-012 - SAF-400-013 - SAF-400-014 - SAF-400-015 - SAF-409-002 - SAF-502-007 - SAF-400-016 - SAF-503-001 - SAF-503-002 - SAF-503-003 - SAF-503-004 - SGN-404-001 - SGN-404-002 - SGN-422-001 - SGN-500-001 - SGN-500-002 - SGN-502-001 - SGN-502-002 - SGN-502-003 - SGN-502-004 - HEALTH-401-001 - STS-400-001 - STS-404-001 - STS-403-001 - STS-403-002 - ONB-409-001 - ONB-202-001 - PHONE-409-001 - PHONE-400-001 - PHONE-422-002 - PHONE-400-003 - PHONE-429-001 - PHONE-429-002 - PHONE-409-002 - PHONE-502-001 - PHONE-403-001 - STR-404-001 - STR-409-001 - STR-400-001 - CON-404-001 - CON-409-001 - CON-401-001 - CON-400-001 - UST-404-001 - UST-403-001 - UST-400-001 - UST-409-001 - UST-503-001 - UCO-404-001 - UCO-403-001 - TOL-404-001 - RUL-404-001 - RUL-403-001 - RUL-400-001 - RUN-404-001 - RUN-403-001 - RUN-409-001 - RUN-400-001 - RUN-400-002 - RUN-404-002 - RUN-409-002 - RUN-409-003 - RUN-208-001 - RUN-400-003 - RUN-408-001 - ACC-404-001 - ACC-409-001 - ACC-403-001 - ACC-400-001 - ACC-400-002 - ACC-502-001 - ACC-403-002 - OBK-401-001 - OBK-400-001 - OBK-502-001 - TXN-404-001 - TXN-403-001 - TXN-500-001 - TXN-400-001 - TXN-400-002 - TXN-409-001 - TXN-409-002 - TXN-409-003 - TXN-422-001 - RCT-400-001 - RCT-400-002 - RCT-500-001 - RCT-404-001 - RCT-500-002 - RCT-500-003 - RCT-429-001 - INS-404-001 - INS-403-001 - INS-409-001 - INS-400-001 - INS-500-002 - INS-500-003 - INS-503-001 - CRD-404-001 - CRD-403-001 - CRD-404-002 - CRD-400-001 - CRD-403-002 - CRD-401-001 - CRD-404-003 - CRD-409-001 - CRD-502-001 - BUD-404-001 - BUD-403-001 - BUD-409-001 - BUD-400-001 - BUD-400-002 - BUD-400-003 - BUD-400-004 - BUD-400-005 - BUD-403-002 - BUD-500-001 - BUD-429-001 - CHT-404-001 - CHT-403-001 - CHT-404-002 - CHT-409-001 - CHT-400-001 - CHA-415-001 - CHA-413-001 - CHA-500-001 - CHA-429-001 - AGT-401-001 - AGT-401-002 - AGT-401-003 - AGT-401-004 - AGT-401-005 - AGT-403-001 - AGT-403-002 - AGT-404-001 - AGT-404-002 - AGT-429-001 - AST-404-001 - AST-502-001 - AST-400-001 - BNK-500-001 - BNK-400-001 - BNK-404-001 - BNK-403-001 - BNK-409-001 - BNK-400-002 - BNK-202-001 - BNK-400-003 - BNK-400-004 - BNK-502-001 - BNK-410-001 - BNK-403-002 - BNK-400-005 - BNK-400-006 - BNK-404-002 - BNK-403-003 - BNK-422-001 - WID-404-001 - WID-403-001 - WID-400-001 - WID-400-002 - GATE-403-001 - GATE-429-001 - GATE-503-001 - SIS-401-001 - SIS-401-002 - SIS-404-001 - SIS-403-001 - SIS-403-002 - SIS-403-003 - SIS-404-002 - SIS-403-004 - SIS-403-005 - SIS-403-006 - SIS-409-001 - SIS-409-002 - SIS-404-003 - SIS-502-001 - SIS-502-002 - SIS-502-003 - SIS-401-003 - SIS-409-003 - SIS-502-004 - SIS-502-005 - SIS-409-004 - SIS-409-005 - SIS-400-001 - ORG-401-001 - ORG-503-001 - SIS-404-004 - SIS-409-006 - SIS-422-002 - SIS-404-005 - SIS-422-003 - SIS-404-006 - SIS-404-007 - SIS-422-004 - SIS-409-008 - SIS-404-008 - SIS-409-007 - SIS-422-005 - SIS-422-006 - SIS-422-007 - SIS-502-006 - PINT-400-001 - PINT-400-002 - PINT-400-003 - PINT-400-004 - PINT-400-005 - PINT-400-006 - PINT-400-007 - PINT-401-001 - PINT-401-002 - PINT-401-005 - PINT-403-001 - PINT-403-002 - PINT-404-001 - PINT-409-001 - PINT-409-002 - PINT-409-003 - PINT-409-004 - PINT-409-005 - PINT-410-001 - PINT-410-002 - PINT-424-001 - PINT-424-002 - PINT-424-003 - PINT-424-004 - PINT-424-005 - PINT-424-006 - PINT-424-007 - PINT-429-001 - PINT-401-003 - PINT-401-004 - PINT-401-006 - PINT-403-003 - PINT-403-004 - PINT-403-005 - PINT-403-006 - PINT-403-007 - PINT-403-008 - PINT-409-006 - PINT-422-001 - PINT-422-002 - PINT-422-003 - PINT-422-004 - PINT-422-005 - PINT-422-006 - PINT-500-001 - PAY-404-001 - PAY-403-001 - PAY-409-001 - PAY-409-002 - PAY-409-003 - PAY-410-001 - PAY-422-001 - PAY-422-002 - PAY-400-003 - PAY-400-004 - PAY-400-005 - PAY-400-006 - PAY-422-003 - PAY-501-001 - PAY-502-001 - PAY-504-001 - FAC-400-001 - FAC-400-002 - FAC-400-003 - FAC-400-004 - FAC-400-005 - FAC-409-001 - FAC-422-001 - FAC-422-002 - FAC-422-003 - FAC-502-001 - FAC-502-002 - FAC-503-001 - SRI-400-001 - SRI-400-002 - SRI-404-001 - SRI-400-003 - SIW-401-001 - SIW-401-002 - SIW-401-003 - SIW-401-004 - SIW-401-005 - SIW-401-006 - SIW-400-001 - SIW-400-002 - SIW-502-001 - SIW-429-001 - SIW-429-002 - SIW-404-001 - SIW-404-002 - SIW-401-007 - SIW-401-008 - SIW-401-009 - SIW-401-010 - IPA-404-001 - IPA-400-001 - IPA-400-002 - IPA-409-001 - IPA-403-001 - IPA-401-001 - IPA-401-002 - IPA-401-003 - IPA-401-004 - IPA-409-002 - IPA-409-003 - IPA-422-001 - IPA-424-001 - IPA-409-004 - IPA-409-005 - IPA-422-002 - IPA-424-002 - IPA-409-006 - ALC-401-001 - ALC-400-001 - MLD-401-001 - MLD-502-001 - RMP-400-001 - RMP-400-002 - RMP-400-003 - RMP-400-004 - RMP-403-001 - RMP-403-002 - RMP-404-001 - RMP-502-001 - ONB-400-001 - ONB-400-002 - ONB-400-003 - ONB-400-004 - ONB-409-003 - ONB-409-002 - PRV-404-001 - MRC-404-001 - MRC-400-001 - MRC-401-001 - MRC-403-001 - MRC-503-001 - RPC-400-001 - RPC-404-002 - RPC-402-001 - RPC-404-001 - RPC-400-002 - RPC-502-001 - RPC-409-001 - RPC-409-002 - RPC-409-003 - RPC-401-001 - RPC-403-001 - CLI-400-001 - CLI-401-001 - CLI-401-002 - CLI-401-003 - CLI-401-004 - CLI-403-001 - CLI-404-001 - CLI-409-001 - CLI-410-001 - CLI-503-001 - CALLER-400-001 - CALLER-403-001 - CALLER-503-001 - DMO-403-001 - VIC-404-001 - VIC-409-001 - VIC-409-002 - VIC-409-003 - VIC-502-001 - VIC-502-002 - VIC-502-003 - VIC-502-004 - VIC-502-005 - VIC-503-001 - TAP-503-001 - TAP-502-001 - GEN-400-001 - SYS-500-001 title: APIErrorCode ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type input: title: Input ctx: type: object title: Context type: object required: - loc - msg - type title: ValidationError ````