Card Payments

Conto supports connecting existing payment cards to the policy engine, giving you spend limits, merchant controls, time windows, and MCC-based restrictions for agent card usage.

Issuing new cards directly through Conto is not yet generally available. Today, you can connect any existing card manually and enforce policies through the SDK approve/confirm flow.

Connecting a Card

Register an existing card by providing its last 4 digits, brand, and spend limits. Card management routes currently use the signed-in dashboard session; they do not accept agent SDK keys. Set CONTO_DASHBOARD_COOKIE to the full Cookie header from a signed-in dashboard request.

curl -X POST https://conto.finance/api/cards \
  -H "Cookie: $CONTO_DASHBOARD_COOKIE" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "MANUAL",
    "name": "Marketing Card",
    "last4": "4242",
    "brand": "VISA",
    "cardType": "VIRTUAL",
    "spendLimitDaily": 1000,
    "spendLimitPerTx": 500
  }'

Response:

{
  "card": {
    "id": "cmm5e0crd000l49h7fouwe11p",
    "name": "Marketing Card",
    "provider": "MANUAL",
    "last4": "4242",
    "brand": "VISA",
    "status": "ACTIVE"
  }
}

You can also create cards from the dashboard at Cards > Create Card.

Assigning Cards to Agents

After connecting a card, assign it to an agent with per-agent limits:

curl -X POST https://conto.finance/api/agents/{agentId}/cards \
  -H "Cookie: $CONTO_DASHBOARD_COOKIE" \
  -H "Content-Type: application/json" \
  -d '{
    "cardId": "cmm5e0crd000l49h7fouwe11p",
    "spendLimitPerTx": 250,
    "spendLimitDaily": 500,
    "allowedDays": ["Mon", "Tue", "Wed", "Thu", "Fri"],
    "allowedHoursStart": 9,
    "allowedHoursEnd": 17,
    "blockedCategories": ["7995"]
  }'

Agent-level limits cannot exceed card-level limits. One card can be assigned to multiple agents, each with their own spend controls.

Card State Management

Pause, resume, or cancel cards from the dashboard or API:

# Pause a card
curl -X PATCH https://conto.finance/api/cards/{cardId}/state \
  -H "Cookie: $CONTO_DASHBOARD_COOKIE" \
  -d '{ "state": "PAUSED" }'

# Resume a card
curl -X PATCH https://conto.finance/api/cards/{cardId}/state \
  -H "Cookie: $CONTO_DASHBOARD_COOKIE" \
  -d '{ "state": "ACTIVE" }'

# Cancel a card (deactivates all agent links)
curl -X PATCH https://conto.finance/api/cards/{cardId}/state \
  -H "Cookie: $CONTO_DASHBOARD_COOKIE" \
  -d '{ "state": "CANCELLED" }'

Linking Policies to Cards

Beyond the per-agent field-based limits, you can link named policies to cards. This uses the same Policy / PolicyRule framework as wallets and agents.

# Link a policy to a card
curl -X POST https://conto.finance/api/cards/{cardId}/policies \
  -H "Cookie: $CONTO_DASHBOARD_COOKIE" \
  -d '{ "policyId": "cmm5c0pol000l49h7dmsuc11p" }'

# List linked policies
curl https://conto.finance/api/cards/{cardId}/policies \
  -H "Cookie: $CONTO_DASHBOARD_COOKIE"

# Unlink a policy
curl -X DELETE https://conto.finance/api/cards/{cardId}/policies/{policyId} \
  -H "Cookie: $CONTO_DASHBOARD_COOKIE"

Card policies support all standard rule types plus card-specific ones:

Rule Type	Description
`CARD_ALLOWED_MCCS`	Whitelist merchant category codes
`CARD_BLOCKED_MCCS`	Blocklist merchant category codes
`CARD_ALLOWED_MERCHANTS`	Whitelist merchant names/IDs
`CARD_BLOCKED_MERCHANTS`	Blocklist merchant names/IDs
`CARD_MAX_AMOUNT`	Per-card transaction amount ceiling

See Advanced Policies for value formats.

Policy Enforcement

Card payments are evaluated through two layers:

Layer 1: Agent-Card Limits

Field-based limits set when assigning a card to an agent:

Per-transaction, daily, weekly, monthly spend limits
Time windows (allowed days and hours)
MCC category allow/block lists
Merchant allow/block lists

Layer 2: Policy Rule Engine

Database-defined policies linked to the card or agent:

All standard rule types (velocity, geographic, approval thresholds)
Card-specific MCC and merchant rules
Priority-ordered evaluation with AND logic

Both layers run together. The first violation from either layer denies the payment.

SDK Approve/Confirm Flow

Agents use the approve/confirm pattern before charging a connected card:

Request Approval

Agent calls POST /api/sdk/cards/approve before charging the card.

curl -X POST https://conto.finance/api/sdk/cards/approve \
  -H "Authorization: Bearer $CONTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "cardId": "cmm5e0crd000l49h7fouwe11p",
    "amount": 99.99,
    "merchantName": "AWS",
    "merchantCategory": "5734",
    "purpose": "EC2 instance charges"
  }'

Receive Approval

Conto evaluates both policy layers and returns an approval token (valid 5 minutes).

{
  "approved": true,
  "requestId": "cmm5e1crq001m49h7fouwe22q",
  "approvalToken": "a1b2c3...",
  "expiresAt": "2026-06-15T10:05:00Z",
  "card": { "last4": "4242", "brand": "VISA" },
  "limits": { "remainingDaily": 400.01, "remainingPerTx": 500 }
}

Charge the Card

Agent processes the card charge through its own payment integration.

Confirm Payment

Agent calls POST /api/sdk/cards/{requestId}/confirm with the transaction reference.

curl -X POST https://conto.finance/api/sdk/cards/cmm5e1crq001m49h7fouwe22q/confirm \
  -H "Authorization: Bearer $CONTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "approvalToken": "a1b2c3...",
    "externalTxId": "ch_1234567890",
    "authorizationCode": "A1B2C3",
    "actualAmount": 99.99
  }'

You can also include merchantDetails if the card processor returns the settled merchant name, MCC, or location after authorization.

API Reference

Endpoint	Method	Auth	Description
`/api/cards`	GET	Dashboard session	List all cards
`/api/cards`	POST	Dashboard session	Connect a card (manual)
`/api/cards/{id}`	GET	Dashboard session	Card details
`/api/cards/{id}`	PATCH	Dashboard session	Update card limits/settings
`/api/cards/{id}/state`	PATCH	Dashboard session	Change card state
`/api/cards/{id}/policies`	GET	Dashboard session	List linked policies
`/api/cards/{id}/policies`	POST	Dashboard session	Link a policy
`/api/cards/{id}/policies/{policyId}`	DELETE	Dashboard session	Unlink a policy
`/api/agents/{id}/cards`	GET	Dashboard session	List agent’s cards
`/api/agents/{id}/cards`	POST	Dashboard session	Assign card to agent
`/api/sdk/cards/approve`	POST	Agent SDK key	SDK: request card approval
`/api/sdk/cards/{id}/confirm`	POST	Agent SDK key	SDK: confirm card payment

Card Alert Types

Card transactions are monitored for anomalies after each confirmed payment. These alerts are created automatically:

Alert Type	Severity	Trigger
`CARD_SPEND_VELOCITY`	MEDIUM/HIGH	Current hour spend exceeds 3x the 30-day hourly average
`CARD_LARGE_TX`	MEDIUM/HIGH	Single transaction exceeds 3x the 30-day per-transaction average. HIGH if ratio exceeds 10x
`CARD_NEW_MERCHANT`	LOW	First transaction with a given merchant
`CARD_RAPID_SWITCHING`	MEDIUM/HIGH	More than 5 distinct merchants within 60 minutes. HIGH if more than 10
`CARD_DAILY_BURN`	MEDIUM/HIGH	Daily spend exceeds 80% of daily limit. HIGH if exceeds 95%

Card alerts require sufficient transaction history for statistical detection. CARD_SPEND_VELOCITY needs at least 5 days of history and 10 prior transactions. CARD_LARGE_TX needs at least 10 prior transactions.

Next Steps

Card Management Guide

Dashboard walkthrough for managing cards

Advanced Policies

Card-specific policy rule types

Standard Payments

Stablecoin payment flow

Spend Limits

Configure spending controls

Start

Products

Build

Guides

Reference

Changelog

Card Payments

Card Payments

Connecting a Card

Assigning Cards to Agents

Card State Management

Linking Policies to Cards

Policy Enforcement

Layer 1: Agent-Card Limits

Layer 2: Policy Rule Engine

SDK Approve/Confirm Flow

API Reference

Card Alert Types

Next Steps

Card Management Guide

Advanced Policies

Standard Payments

Spend Limits

​Card Payments

​Connecting a Card

​Assigning Cards to Agents

​Card State Management

​Linking Policies to Cards

​Policy Enforcement

​Layer 1: Agent-Card Limits

​Layer 2: Policy Rule Engine

​SDK Approve/Confirm Flow

​API Reference

​Card Alert Types

​Next Steps

Card Management Guide

Advanced Policies

Standard Payments

Spend Limits

Card Payments

Connecting a Card

Assigning Cards to Agents

Card State Management

Linking Policies to Cards

Policy Enforcement

Layer 1: Agent-Card Limits

Layer 2: Policy Rule Engine

SDK Approve/Confirm Flow

API Reference

Card Alert Types

Next Steps