Skip to main content

​
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.
Stripe Issuing and Lithic card provisioning (issuing new cards directly through Conto) is coming soon. Currently, 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: 
curl -X POST https://conto.finance/api/cards \
  -H "Authorization: Bearer $CONTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "MANUAL",
    "name": "Marketing Card",
    "last4": "4242",
    "brand": "VISA",
    "cardType": "VIRTUAL",
    "spendLimitDaily": 1000,
    "spendLimitPerTx": 500
  }'
Response: 
{
  "card": {
    "id": "clx_abc123",
    "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 "Authorization: Bearer $CONTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "cardId": "clx_abc123",
    "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 "Authorization: Bearer $CONTO_API_KEY" \
  -d '{ "state": "PAUSED" }'

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

# Cancel a card (deactivates all agent links)
curl -X PATCH https://conto.finance/api/cards/{cardId}/state \
  -H "Authorization: Bearer $CONTO_API_KEY" \
  -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 "Authorization: Bearer $CONTO_API_KEY" \
  -d '{ "policyId": "policy_abc123" }'

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

# Unlink a policy
curl -X DELETE https://conto.finance/api/cards/{cardId}/policies/{policyId} \
  -H "Authorization: Bearer $CONTO_API_KEY"
Card policies support all standard rule types plus card-specific ones:
Rule TypeDescription
CARD_ALLOWED_MCCSWhitelist merchant category codes
CARD_BLOCKED_MCCSBlocklist merchant category codes
CARD_ALLOWED_MERCHANTSWhitelist merchant names/IDs
CARD_BLOCKED_MERCHANTSBlocklist merchant names/IDs
CARD_MAX_AMOUNTPer-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:
1

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_SDK_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "cardId": "clx_abc123",
    "amount": 99.99,
    "merchantName": "AWS",
    "merchantCategory": "5734",
    "purpose": "EC2 instance charges"
  }'
2

Receive Approval

Conto evaluates both policy layers and returns an approval token (valid 5 minutes).
{
  "approved": true,
  "requestId": "cpr_xyz",
  "approvalToken": "a1b2c3...",
  "expiresAt": "2025-06-15T10:05:00Z",
  "card": { "last4": "4242", "brand": "VISA" },
  "limits": { "remainingDaily": 400.01, "remainingPerTx": 500 }
}
3

Charge the Card

Agent processes the card charge through its own payment integration.
4

Confirm Payment

Agent calls POST /api/sdk/cards/{requestId}/confirm with the transaction reference.
curl -X POST https://conto.finance/api/sdk/cards/cpr_xyz/confirm \
  -H "Authorization: Bearer $CONTO_SDK_KEY" \
  -d '{
    "approvalToken": "a1b2c3...",
    "externalTxId": "ch_1234567890",
    "actualAmount": 99.99
  }'

​
Webhook Authorizations (Coming Soon)

Webhook-based real-time authorization requires Stripe Issuing or Lithic integration, which is coming soon. The webhook handlers are built and ready for when provider integration is enabled.
When Stripe Issuing or Lithic integration is available, real-time authorization webhooks will provide automatic policy enforcement without the SDK approve/confirm flow. The card provider sends an authorization request to Conto, which evaluates policies and responds with approve or decline within 2 seconds.
ProviderWebhook EndpointSecret Env Var
Stripe Issuing/api/webhooks/cards/stripeSTRIPE_ISSUING_WEBHOOK_SECRET
Lithic/api/webhooks/cards/lithicLITHIC_WEBHOOK_SECRET
Privacy.com/api/webhooks/cards/privacyPRIVACY_WEBHOOK_SECRET

​
API Reference

EndpointMethodDescription
/api/cardsGETList all cards
/api/cardsPOSTConnect a card (manual)
/api/cards/{id}GETCard details
/api/cards/{id}PATCHUpdate card limits/settings
/api/cards/{id}/statePATCHChange card state
/api/cards/{id}/policiesGETList linked policies
/api/cards/{id}/policiesPOSTLink a policy
/api/cards/{id}/policies/{policyId}DELETEUnlink a policy
/api/agents/{id}/cardsGETList agent’s cards
/api/agents/{id}/cardsPOSTAssign card to agent
/api/sdk/cards/approvePOSTSDK: request card approval
/api/sdk/cards/{id}/confirmPOSTSDK: confirm card payment

​
Roadmap

FeatureStatus
Manual card connection + policy enforcementAvailable
SDK approve/confirm flowAvailable
Card policy linking (CardPolicy)Available
Stripe Issuing card provisioningComing soon
Lithic card provisioningComing soon
Provider card importComing soon
Real-time webhook authorizationsComing soon

​
Card Alert Types

Card transactions are monitored for anomalies after each confirmed payment. These alerts are created automatically:
Alert TypeSeverityTrigger
CARD_SPEND_VELOCITYMEDIUM/HIGHCurrent hour spend exceeds 3x the 30-day hourly average
CARD_LARGE_TXMEDIUM/HIGHSingle transaction exceeds 3x the 30-day per-transaction average. HIGH if ratio exceeds 10x
CARD_NEW_MERCHANTLOWFirst transaction with a given merchant
CARD_RAPID_SWITCHINGMEDIUM/HIGHMore than 5 distinct merchants within 60 minutes. HIGH if more than 10
CARD_DAILY_BURNMEDIUM/HIGHDaily 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