---
title: Connect a customer | API Docs
description: Link a customer's Agentcard Wallet to your organization with a one-time verification in the messaging channel.
---

Before an agent can pay for a customer, that customer connects their Agentcard Wallet to your organization once. You start the connection with their **handle** (phone in E.164, or email); Linq drives a one-time code and consent through the messaging channel; you complete it with a verify call. After that, payments for the handle work without re-verifying.

Base URL for all calls: `https://api.linqapp.com/api/partner/v3`.

## 1. Start the connection

Terminal window

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

```
{
  "handle": "+14155550123",
  "status": "not_connected",
  "connect_id": "cs_01HZY8"
}
```

Hold the `connect_id` — you need it to submit the code. Nothing on Linq’s side persists it; it comes back from the provider and is required again to verify. Linq now runs the one-time code and consent ceremony with the customer in the messaging channel.

## 2. The customer adds a card

The customer opens the Agentcard wallet and adds the card they want their agent to spend from. Card details are entered directly into Agentcard — **neither Linq, your app, nor the agent ever sees the raw card number.**

![The Agentcard Wallet "Add Card" screen inside an iMessage thread, with fields for card number, expiry, and CVC, and an "Add Card" button.](/images/agentcard-add-card.png)

## 3. The customer authorizes with a one-time code

Agentcard sends a one-time code the customer confirms to prove ownership.

![The "Authorize card" screen showing a six-digit one-time code entry, a "didn't receive a code? Resend code" link, and an "Authorize" button.](/images/agentcard-authorize-code.png)

## 4. The customer confirms and consents

The card is provisioned and the customer agrees to the card network’s terms. Optional biometric (“verify faster”) can be enabled here.

![The card-provisioned confirmation screen showing the added card, a "Verified faster" prompt offering face, fingerprint, or screen-lock verification, a terms-of-service consent checkbox, and a "Continue" button.](/images/agentcard-card-consent.png)

## 5. Verify the code to complete the connection

The code reaches you however your channel works — typically the customer replies with it in the thread. Submit it with the `connect_id` from step 1:

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" }'
```

```
{
  "handle": "+14155550123",
  "status": "connected",
  "connect_id": "cs_01HZY8"
}
```

This records the customer’s consent and stores the connection. You’ll also receive a `connection.created` webhook. From here you can [create payments](/guides/agentcard/create-a-payment/index.md) for the handle.

## Check or revoke a connection

Terminal window

```
# Current connection status for a handle
curl https://api.linqapp.com/api/partner/v3/payments/handles/+14155550123/connection \
  -H "Authorization: Bearer $LINQ_API_KEY"


# Revoke the connection
curl -X DELETE https://api.linqapp.com/api/partner/v3/payments/handles/+14155550123/connection \
  -H "Authorization: Bearer $LINQ_API_KEY"
```

Connection statuses: `not_connected`, `pending`, `connected`, `revoked`. If a customer removes the connection you’ll get `connection.revoked`, and new payments for that handle will fail until they reconnect.

## Notes

- The wallet, card entry, and code are all Agentcard-hosted — you never handle PAN/CVC.
- Keep the `connect_id` only until you verify; it’s a temporary ceremony id.

## Next

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