---
title: Overview | API Docs
description: Let an agent pay on a customer's behalf with a single-use virtual card.
---

# Agentcard

Agentcard lets an agent pay on a customer’s behalf. You connect a customer once, then create a payment — the API mints a single-use virtual card scoped to that purchase, and hands the card details back for the agent to complete checkout.

![The Agentcard Wallet intro card inside an iMessage thread, inviting the customer to keep all their cards and create cards for their agent in one place.](/images/agentcard-wallet-intro.png)

## How it works

1. **Connect the provider.** Onboard your organization with `POST /v3/payments/providers/agentcard/connect`, complete the hosted flow, and you’re returned to your `return_url`.
2. **Connect a customer.** Start a connection for a customer handle (phone/email) with `POST /v3/payments/handles/{handle}/connect`. The customer completes a one-time verification through the messaging channel; a `connection.created` webhook fires when they’re connected.
3. **Create a payment.** Call `POST /v3/payments` with the handle, amount, currency, and merchant. The response’s `status` tells you what to do next — `needs_connection`, `awaiting_user_action` (share the returned URL), or `ready` once the card is minted.
4. **Retrieve the card.** When the payment is `ready`, `GET /v3/payments/{paymentId}/credentials` returns a short-lived handoff (a token + fetch URL) the agent uses to read the card number directly from the provider. Card details never pass through Linq.
5. **Track the lifecycle.** Subscribe to `payment.authorized`, `payment.declined`, `connection.created`, and `connection.revoked`. There is no `payment.succeeded` webhook — poll `GET /v3/payments/{paymentId}` to confirm the charge settled.

## Notes

- Amounts are in the currency’s minor units (cents for `usd`).
- A payment is idempotent on the `Idempotency-Key` header.
- Card credentials are display-and-use only and are never stored by Linq.

## Guides

- [Quickstart](/guides/agentcard/quickstart/index.md) — setup to payment in five steps.
- [Connect a customer](/guides/agentcard/connect-a-customer/index.md) — connect and verify, with screens.
- [Create & complete a payment](/guides/agentcard/create-a-payment/index.md) — statuses and retrieval.
- [Cards & credentials](/guides/agentcard/cards-and-credentials/index.md) — the wallet model and the handoff.
- [Webhooks & lifecycle](/guides/agentcard/webhooks/index.md) — events, payloads, and signature verification.
- [Agentcard vs Stripe](/guides/agentcard/agentcard-vs-stripe/index.md) — which provider to use when.
- [Errors, statuses & go-live](/guides/agentcard/errors-and-go-live/index.md) — the production checklist.

See the API reference for full operation, schema, and webhook details: [Payments](/api/resources/payments/index.md), [Payment handles](/api/resources/payment_handles/index.md), [Payment providers](/api/resources/payment_providers/index.md), and [Experiences](/api/resources/experiences/index.md).