> ## Documentation Index
> Fetch the complete documentation index at: https://conto.finance/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Card Payments

> Connect, manage, and enforce policies on payment cards for AI agents

# 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.

<Info>
  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.
</Info>

## 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.

```bash theme={null}
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:**

```json theme={null}
{
  "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:

```bash theme={null}
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:

```bash theme={null}
# 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.

```bash theme={null}
# 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](/policies/advanced#card-payment-rules) 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:

<Steps>
  <Step title="Request Approval">
    Agent calls `POST /api/sdk/cards/approve` before charging the card.

    ```bash theme={null}
    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"
      }'
    ```
  </Step>

  <Step title="Receive Approval">
    Conto evaluates both policy layers and returns an approval token (valid 5 minutes).

    ```json theme={null}
    {
      "approved": true,
      "requestId": "cmm5e1crq001m49h7fouwe22q",
      "approvalToken": "a1b2c3...",
      "expiresAt": "2026-06-15T10:05:00Z",
      "card": { "last4": "4242", "brand": "VISA" },
      "limits": { "remainingDaily": 400.01, "remainingPerTx": 500 }
    }
    ```
  </Step>

  <Step title="Charge the Card">
    Agent processes the card charge through its own payment integration.
  </Step>

  <Step title="Confirm Payment">
    Agent calls `POST /api/sdk/cards/{requestId}/confirm` with the transaction reference.

    ```bash theme={null}
    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.
  </Step>
</Steps>

## 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%                                 |

<Info>
  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.
</Info>

## Next Steps

<CardGroup cols={2}>
  <Card title="Card Management Guide" icon="credit-card" href="/guides/card-management">
    Dashboard walkthrough for managing cards
  </Card>

  <Card title="Advanced Policies" icon="shield" href="/policies/advanced#card-payment-rules">
    Card-specific policy rule types
  </Card>

  <Card title="Standard Payments" icon="wallet" href="/sdk/payments">
    Stablecoin payment flow
  </Card>

  <Card title="Spend Limits" icon="dollar-sign" href="/policies/spend-limits">
    Configure spending controls
  </Card>
</CardGroup>