Conto Card Access

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. Card Access is a separate product package:

npm install @conto_finance/sdk @conto_finance/card-access

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

Open Conto Card Access in the Conto dashboard to see whether the policy backend is enabled, register or manage masked card aliases, review active agent assignments, and monitor reconciliation work. The dashboard cannot verify that the customer’s credential store is isolated from the agent, so the final deployment check remains a customer responsibility.

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.

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.

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.
Filter receipt fields returned to the agent.
Reconcile confirmation-pending executions.
Keep the organization allowlisted until every open request is resolved.

Start

Products

Build

Guides

Reference

Changelog

Conto Card Access

Conto Card Access

What Card Access Controls

Dashboard

Request Path

Create Card Access

Expose the Agent Tool

Handle Uncertain Confirmation

Production Checklist

​Conto Card Access

​What Card Access Controls

​Dashboard

​Request Path

​Create Card Access

​Expose the Agent Tool

​Handle Uncertain Confirmation

​Production Checklist

Conto Card Access

What Card Access Controls

Dashboard

Request Path

Create Card Access

Expose the Agent Tool

Handle Uncertain Confirmation

Production Checklist