---
title: Quickstart | API Docs
description: Let your users connect their cards so their agent can pay on their behalf from the Agentcard Wallet — setup to payment in five steps.
---

Agentcard lets your users connect their cards so their agent can make payments on their behalf using cards from the **Agentcard Wallet**. Your users add their cards once; from then on their agent pays merchants with a card from the wallet — the card details are handed to the agent just in time and are never stored by Linq.

## Prerequisites

- A Linq organization with API access. Create an API token at [dashboard.linqapp.com/api-tooling](https://dashboard.linqapp.com/api-tooling) and send it on every request as `Authorization: Bearer <LINQ_API_KEY>`.
- Base URL: `https://api.linqapp.com/api/partner/v3`.
- A webhook endpoint to receive payment and connection events (see [Webhooks & lifecycle](/guides/agentcard/webhooks/index.md)).

## The five steps

1. **Connect the provider (once)**

   Onboard your organization to Agentcard from the Linq dashboard — go to [**Payments**](https://zero.linqapp.com/organization/payments) and connect Agentcard. Do this a single time per org.

2. **Connect a customer**

   Start a connection for a customer **handle** (phone in E.164, or email). Linq drives the one-time code and consent through the messaging channel; hold the returned `connect_id`.

   Terminal window

   ```
   curl -X POST https://api.linqapp.com/api/partner/v3/payments/handles/+14155550123/connect \
     -H "Authorization: Bearer $LINQ_API_KEY"
   ```

   When the customer replies with their code, complete the connection:

   Terminal window

   ```
   curl -X POST https://api.linqapp.com/api/partner/v3/payments/handles/+14155550123/verify \
     -H "Authorization: Bearer $LINQ_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{ "connect_id": "cs_01HZY8", "code": "482913" }'
   ```

   Full walkthrough with screens: [Connect a customer](/guides/agentcard/connect-a-customer/index.md).

3. **Create a payment**

   Call the payments endpoint with the handle, `amount_cents`, currency, and merchant. Send an `Idempotency-Key` so a retry never double-charges.

   Terminal window

   ```
   curl -X POST https://api.linqapp.com/api/partner/v3/payments \
     -H "Authorization: Bearer $LINQ_API_KEY" \
     -H "Idempotency-Key: $(uuidgen)" \
     -H "Content-Type: application/json" \
     -d '{
       "handle": "+14155550123",
       "amount_cents": 2500,
       "currency": "usd",
       "description": "Burger order",
       "merchant": { "name": "DoorDash", "url": "doordash.com" }
     }'
   ```

   `amount_cents: 2500` is **$25.00** — amounts are always in the currency’s minor units.

4. **Retrieve the card**

   When the payment is `ready`, fetch the credential **handoff**. Your agent uses it to read the card directly from Agentcard — the number never passes through Linq.

   Terminal window

   ```
   curl https://api.linqapp.com/api/partner/v3/payments/550e8400-e29b-41d4-a716-446655440000/credentials \
     -H "Authorization: Bearer $LINQ_API_KEY"
   ```

   See [Cards & credentials](/guides/agentcard/cards-and-credentials/index.md) for the handoff shape and how the agent redeems it.

5. **Track the lifecycle**

   Subscribe to webhooks instead of polling: `payment.authorized`, `payment.declined`, `connection.created`, and `connection.revoked`. Treat the event as a nudge and re-fetch the payment for authoritative status — there is no `payment.succeeded` webhook, so poll `GET /payments/{id}` for the final `succeeded` state.

## Notes

- Amounts are in the currency’s minor units — `amount_cents` (cents for `usd`).
- A payment is idempotent on the `Idempotency-Key` header.
- Card credentials are fetched directly from Agentcard and are **never stored by Linq**.

## Next

- [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.
- [Webhooks & lifecycle](/guides/agentcard/webhooks/index.md) — events and payloads.
- [Agentcard vs Stripe](/guides/agentcard/agentcard-vs-stripe/index.md) — pick the right rail.