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

# Conto Card Access

> Run a customer-hosted payment tool that requires Conto approval before customer card code can execute.

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

```bash theme={null}
npm install @conto_finance/sdk @conto_finance/card-access
```

<Warning>
  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`.
</Warning>

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

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

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

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