Conto Card Access

Card Access is a maintenance-only private fallback. Conto is not onboarding new deployments; new connected-card work uses the shared Cards product and Basis Theory provider path. This page remains available for existing pilot recovery and historical integration reference.

Conto Card Access is a customer-hosted payment gate for agents that use an existing customer-owned card. Conto evaluates purchase policy and atomically claims the approval before the customer’s payment executor can run. The package remains private and is not available for new customer installation.

Conto Card Access does not make an existing card non-bypassable. The card can still be used outside the controlled agent path, so every Card Access result reports canBypass: true.

What Card Access Controls

Card Access controls	Card Access does not control
The customer-hosted agent payment endpoint	Issuer or card-network authorization
Conto policy approval before execution	Human or system use of the card elsewhere
One atomic execution claim per approval	PAN, CVC, expiry, or vault-token custody
Confirmation and operator reconciliation	Independent observation of all card transactions
Receipt fields returned to the agent	3DS and issuer challenges

Card Access uses the external-card policy overlay as its policy backend. It does not rename or replace the overlay, checkout relay, or card issuing.

Dashboard

Former pilot organizations can use the direct recovery workspace to review retained claims and reconciliation work. Card Access has been removed from normal navigation, and the global new-spend gate is closed. Cards is the forward product surface for provider-connected cards.

Historical assignment controls

These controls remain documented for prior pilot evidence. New assignments are disabled while the global gate is closed. In an explicitly approved maintenance environment, operators could start from either surface:

Open an agent and select Card Access, then choose Assign alias.
Open Conto Card Access, find an alias, then choose Assign agent.

An assignment can set per-transaction, daily, weekly, and monthly limits; allowed days and hours; merchant and MCC allow or block lists; and optional start and end dates. Conto stores only the alias and masked card details. Assignment lifecycle states are explicit:

State	Effect in the integrated path
`ACTIVE`	New approvals and execution claims are allowed when every other policy passes.
`PAUSED`	New approvals and execution claims are blocked. Unused approvals are cancelled and their reservations are released.
`REVOKED`	The assignment is permanently inactive. A later assignment creates a new lifecycle on the same alias and agent pair.

Claimed purchases remain visible for confirmation or reconciliation after a pause or revocation. Every assignment change is written to the Conto audit log. Use the admin SDK for the same lifecycle:

await admin.cards.updateAgentAssignment(agentId, cardId, {
  timezone: 'America/Los_Angeles',
  spendLimitPerTx: 100,
  spendLimitDaily: 500,
  activeUntil: '2026-09-01T00:00:00.000Z',
});

await admin.cards.pauseForAgent(agentId, cardId);
await admin.cards.resumeForAgent(agentId, cardId);
await admin.cards.revokeFromAgent(agentId, cardId);

Request Path

agent
  -> authenticated customer payment endpoint
  -> Conto Card Access
  -> Conto policy approval
  -> atomic execution claim
  -> customer credential store and payment executor
  -> Conto confirmation

The customer payment endpoint must be the agent’s only payment tool. Do not import the credential store or executor into the agent process.

Human Review

When a matching policy requires human approval, Card Access creates a pending purchase intent without reserving spend or issuing an execution grant. A user with transaction approval permission can approve or reject the intent in Conto Card Access. Approval rechecks the current card, assignment, schedule, limits, and merchant policy before Conto reserves spend. If the recheck passes, Conto creates a five-minute execution grant. The agent retries the same purchase with the same idempotency key to claim that grant and continue. The customer executor cannot run while review is pending. Pending reviews expire after 24 hours. Pausing the alias or pausing or revoking the assignment cancels its pending reviews.

Create Card Access

import { Conto } from '@conto_finance/sdk';
import { ContoCardAccess } from '@conto_finance/card-access';

const conto = new Conto({
  apiKey: process.env.CONTO_AGENT_API_KEY!,
});

const cardAccess = new ContoCardAccess({
  policy: conto.cards,
  integrationId: 'procurement-agent-production',
  deployment: {
    credentialCustody: 'CUSTOMER',
    agentHasRawCredentialAccess: false,
    uncontrolledAgentPaymentPath: false,
  },
  executor: async (purchase) => {
    const credential = await customerSecretStore.getCard(purchase.cardId);
    const result = await customerPaymentTool.charge({
      credential,
      amount: purchase.amount,
      currency: purchase.currency,
      merchantName: purchase.merchantName,
    });

    return {
      externalTxId: result.receiptId,
      authorizationCode: result.authorizationCode,
      actualAmount: result.amount,
      receipt: result,
    };
  },
});

The executor receives the approved merchant and amount. It does not receive the Conto approval token. Card Access rejects likely card numbers, credential fields, secrets, and tokens before sending a purchase intent to Conto.

Expose the Agent Tool

Use the framework-neutral handler from the package:

import { createContoCardAccessHandler } from '@conto_finance/card-access';

export const handlePayment = createContoCardAccessHandler({
  cardAccess,
  authenticate(request) {
    return customerAgentAuth.verify(request.headers.get('authorization'));
  },
  serializeReceipt(receipt) {
    return {
      id: receipt.receiptId,
      amount: receipt.amount,
      merchant: receipt.merchantName,
    };
  },
});

Authentication and a receipt serializer are required. Raw processor responses are never returned by default. Card Access scans the serialized receipt and rejects sensitive fields or likely card numbers before responding to the agent.

Start from the Reference Gateway

The package includes examples/node-server.mjs, a runnable Node gateway with an authenticated POST /card-access/pay endpoint. It calls a private customer executor only after Card Access has claimed a live grant. The private executor resolves the Conto alias to the customer-owned credential and must not be reachable by the agent. After deploying the gateway, run the included non-charging checks:

CARD_ACCESS_URL=https://gateway.example.com/card-access/pay \
CARD_ACCESS_AGENT_TOKEN=replace-with-agent-gateway-token \
npm run conformance

The checks verify authentication, allowed methods, malformed input handling, and credential rejection. Every authenticated probe is invalid before policy evaluation, so the conformance run does not create a purchase intent or call the customer executor.

Run a non-charging staging pilot

The reference deployment includes a container image and Compose stack. It builds the SDK and Card Access from the same source commit and runs a private executor that returns deterministic mock receipts without resolving or charging a card.

docker compose \
  --env-file /secure/path/card-access.staging.env \
  -f packages/card-access/examples/compose.staging.yaml \
  up --build -d

curl --fail http://localhost:8787/healthz
curl --fail http://localhost:8787/readyz

Copy packages/card-access/examples/staging.env.example outside the repository and replace every placeholder before launch. The gateway provides redacted JSON logs, authenticated operational alerts, bounded request and upstream timeouts, readiness draining, and graceful shutdown. The non-charging executor has no host port and is available only on its internal container network.

The included executor is staging-only and cannot charge a card. Replace it with the customer’s private, credential-owning payment service before a real payment test. Card Access remains canBypass=true in either deployment.

Handle Uncertain Confirmation

If payment code runs but confirmation to Conto fails, Card Access raises ContoCardAccessConfirmationPendingError. Persist the receipt and confirmation input securely. Retry only cardAccess.retryConfirmation(error). Never execute the purchase again.

Production Checklist

Remove raw credentials from agent prompts, tools, environment variables, and readable logs.
Remove all uncontrolled payment tools from the agent.
Keep the executor private to the customer-hosted service.
Authenticate every request to the Card Access endpoint.
Use one stable idempotency key per purchase intent.
Retry that same intent only after a pending human review is approved.
Filter receipt fields returned to the agent.
Reconcile confirmation-pending executions.
Pause or revoke stale agent assignments and review the assignment audit trail.
Keep the organization allowlisted until every open request is resolved.

Start

Products

Build

Guides

Reference

Changelog

Conto Card Access (maintenance reference)

Conto Card Access

What Card Access Controls

Dashboard

Historical assignment controls

Request Path

Human Review

Create Card Access

Expose the Agent Tool

Start from the Reference Gateway

Run a non-charging staging pilot

Handle Uncertain Confirmation

Production Checklist

​Conto Card Access

​What Card Access Controls

​Dashboard

​Historical assignment controls

​Request Path

​Human Review

​Create Card Access

​Expose the Agent Tool

​Start from the Reference Gateway

​Run a non-charging staging pilot

​Handle Uncertain Confirmation

​Production Checklist

Conto Card Access

What Card Access Controls

Dashboard

Historical assignment controls

Request Path

Human Review

Create Card Access

Expose the Agent Tool

Start from the Reference Gateway

Run a non-charging staging pilot

Handle Uncertain Confirmation

Production Checklist