---
title: "Start a card attachment"
method: POST
path: "/api/v2/attach"
tags: ["Card attachment"]
---

# Start a card attachment

`POST /api/v2/attach`

Start attaching the connected user's own card. Returns a hosted `attach_url` for the user to open — adding the card takes about a minute (a one-time code from their bank, then a passkey). The card number is entered on the hosted page only; it never passes through your servers. Once attached, cards created over MCP charge this card directly — no identity verification and no wallet funding.

## Request body

- object
  - `user_id` string, required — The connected user's id.

## Response `200`

A card is already attached for this user — nothing to do.

- CardAttachment
  - `object` 'card_attachment', required
  - `id` string, required — The attachment id.
  - `user_id` string, required
  - `status` 'pending' | 'active' | 'ineligible', required — `pending` — the user has not finished the attach link. `active` — attached; `create_card` now mints against this card. `ineligible` — this card cannot be attached; fall back to wallet funding + `create_card`.
  - `attach_url` string — The hosted link the user opens to add their card. Present only on the start response.
  - `expires_at` string, date-time — When the attach link expires (48 hours). Present only on the start response.
  - `card` object — Display details of the attached card. Present when status is `active`.
    - `network` string, nullable
    - `brand` string, nullable
    - `last4` string, nullable
    - `art_url` string, nullable
  - `reason` string — Why the card cannot be attached (e.g. `issuer_excluded`, `commercial_card`). Present when status is `ineligible`.
  - `message` string — Human-readable guidance. Present when status is `ineligible`.

## Other responses

- `201` — The attachment was started — send the user the `attach_url`.
- `400` — `invalid_request` — missing `user_id`.
- `401` — `unauthorized` — the platform access token is missing or expired. Exchange your client credentials for a fresh one.
- `403` — `attach_unavailable` — card attachment is not available; fall back to wallet funding + `create_card`.
- `404` — `connection_not_found` — no connection exists for that user under your client.
- `409` — `user_conflict` — the email on file in your organization belongs to a different account. Contact support.
- `422` — `user_info_required` — a phone number and recorded consent are required first; `missing_fields` names what to collect (`phone_number` via `POST /api/v2/wallet/phone/start`, `consent` via `POST /api/v2/connect/consent`).
- `502` — `attach_failed` — the attachment could not be started; retry.
- `503` — `attach_unavailable` — temporarily unavailable; retry shortly.

---

[API](https://skmtc.dev/agentcard/apis/agentcard-api.md) · [All operations](https://skmtc.dev/agentcard/apis/agentcard-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/agentcard/agentcard-api/revisions/638d12c8303f/schema)