---
title: Cards & credentials | API Docs
description: How the cards your users connect to the Agentcard Wallet are used, and how the credential handoff reaches your agent.
---

Your users connect their cards to the **Agentcard Wallet**. When their agent needs to pay, Agentcard provides a card from the wallet for that one payment. Linq hands your agent a short **handoff** — not the raw card — and the agent reads the card directly from Agentcard.

## One card per payment

- The agent gets a card from the user’s wallet, scoped to that payment and used once.
- The card is scoped to the payment’s `amount_cents`, `currency`, and `merchant`.
- There’s nothing for you to store, rotate, or clean up — each payment gets its own.

![The customer's Agentcard Wallet listing their added cards as stacked card tiles.](/images/agentcard-wallet-cards.png)

## The credential handoff

When a payment is `ready`, fetch the handoff from Linq:

Terminal window

```
curl https://api.linqapp.com/api/partner/v3/payments/{paymentId}/credentials \
  -H "Authorization: Bearer $LINQ_API_KEY"
```

```
{
  "handoff": {
    "provider": "agentcard",
    "user_token": "<short-lived bearer>",
    "card_ref": "card_7h2k",
    "fetch_url": "https://api.agentcard.sh/api/v2/cards/card_7h2k"
  }
}
```

| Field        | What it is                                                |
| ------------ | --------------------------------------------------------- |
| `provider`   | The card provider (`agentcard`).                          |
| `user_token` | A short-lived bearer to fetch the card from the provider. |
| `card_ref`   | The card’s id at the provider.                            |
| `fetch_url`  | Where the agent fetches the actual card.                  |

## Redeeming the handoff

Your agent calls `fetch_url` with the `user_token` to read the card, then enters it at the merchant:

Terminal window

```
curl "$FETCH_URL" -H "Authorization: Bearer $USER_TOKEN"
```

- **Never through Linq.** The card number is fetched directly from Agentcard; it does not pass through Linq’s servers.
- **Short-lived.** The `user_token` expires quickly — fetch the card right before the agent pays, not ahead of time.
- **Do not persist PAN/CVC.** Use the card details in memory and discard them.

## What the customer sees

The customer can review the card and every transaction in their wallet — you don’t build any of this UI.

![The Agentcard Wallet "All transactions" view listing the customer's card activity.](/images/agentcard-wallet-transactions.png)

## Handling declines

If the charge is declined, the payment goes to `declined` — create a **new** payment (and fetch a new handoff) to retry. Don’t reuse a spent handoff.

## Next

- [Create & complete a payment](/guides/agentcard/create-a-payment/index.md)
- [Webhooks & lifecycle](/guides/agentcard/webhooks/index.md)