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

# Connected-card checkout

> Request a checkout credential, acknowledge delivery, and handle retries.

[Connect a card and verify its authorization](/docs/guides/connected-cards) first. Use an SDK version with `conto.connectedCards` and an agent key with `transactions:read` for listing and `payments:approve` for requests and acknowledgment. See [authentication](/docs/sdk/authentication).

## Request and use a credential

Call `conto.connectedCards.list()` to find the agent’s masked cards and mandates, then select the card and verified mandate for your purchase. A credential request is called a **draw**. Use a stable 8–128 character idempotency key per draw. Amounts are in USD cents: `2500` means **\$25.00**.

```typescript theme={null}
import { Conto } from '@conto_finance/sdk';
import { completeAuthorizedCheckout } from './trusted-checkout';

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

const draw = await conto.connectedCards.draw({
  cardId: process.env.CONTO_CARD_ID!,
  mandateId: process.env.CONTO_MANDATE_ID!,
  idempotencyKey: 'office-supplies-order-1042',
  amountMinor: 2500,
  currency: 'USD',
  merchant: {
    merchantName: 'Office Supply Store',
    merchantCategory: '5943',
    merchantCountry: 'US',
  },
});

if (draw.reconciliationRequired) {
  throw new Error('Review the existing card request before checkout');
}
if (draw.decision !== 'APPROVED' || !draw.credential) {
  throw new Error('No fresh checkout credential is available');
}
if (!draw.credentialExpiresAt || Date.parse(draw.credentialExpiresAt) <= Date.now()) {
  throw new Error('Checkout credential has expired');
}

await conto.connectedCards.acknowledgeDelivery(draw.requestId);

// Your checkout integration; keep the credential in memory only.
const receipt = await completeAuthorizedCheckout({
  requestId: draw.requestId,
  credential: draw.credential,
  amountMinor: 2500,
  currency: 'USD',
});
```

`completeAuthorizedCheckout` is your application’s function. It must use the authorized merchant and checkout origin, enforce the purchase amount, and prevent duplicate checkout. Never persist credentials or expose them in prompts, tool results, logs, traces, or screenshots.

## Decisions and retries

| Result                                                   | What to do                                                                                                       |
| -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| `APPROVED` with a fresh credential                       | Check expiry, acknowledge delivery, then complete checkout.                                                      |
| `DENIED`                                                 | Stop and inspect `reasons`.                                                                                      |
| `REQUIRES_APPROVAL`                                      | Wait for review on the agent’s card page, then retry the original input and key. Conto checks the request again. |
| Replay without a credential, or `reconciliationRequired` | Investigate the existing request before another issuance or checkout attempt.                                    |

Credentials are returned only once. The SDK does not automatically retry `draw()`, and reusing a key cannot retrieve a lost credential. Do not generate a new key to recover an uncertain result. Issued allowance capacity remains consumed even if checkout fails.

`acknowledgeDelivery()` is safe to retry for the same request. It records receipt of the credential, **not payment settlement**. Keep the request ID and non-sensitive order references, and confirm the purchase against the merchant receipt and card activity. Contact support if the outcome remains unclear.

## HTTP endpoints

| Method | Endpoint                                                 | Agent scope         |
| ------ | -------------------------------------------------------- | ------------------- |
| `GET`  | `/api/sdk/connected-cards`                               | `transactions:read` |
| `POST` | `/api/sdk/connected-cards/draws`                         | `payments:approve`  |
| `POST` | `/api/sdk/connected-cards/draws/{requestId}/acknowledge` | `payments:approve`  |

Use bearer authentication. Match the verified mandate’s merchant details; optional merchant fields include `merchantId`, `merchantCategory` (four-digit MCC), and `merchantCountry` (two- or three-letter code).