Start a card attachment

curl --request POST \
  --url https://api.agentcard.sh/api/v2/attach \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "user_id": "usr_123"
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({user_id: 'usr_123'})
};

fetch('https://api.agentcard.sh/api/v2/attach', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.agentcard.sh/api/v2/attach"

payload = { "user_id": "usr_123" }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "object": "card_attachment",
  "id": "ca_123",
  "user_id": "usr_123",
  "status": "active",
  "card": {
    "network": "visa",
    "brand": "Visa",
    "last4": "4242",
    "art_url": null
  }
}

{
  "object": "card_attachment",
  "id": "ca_123",
  "user_id": "usr_123",
  "status": "pending",
  "attach_url": "https://agentcard.sh/attach/…",
  "expires_at": "2026-07-23T00:00:00.000Z"
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "docs": "<string>",
    "field_errors": {},
    "warnings": [
      "<string>"
    ]
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "docs": "<string>",
    "field_errors": {},
    "warnings": [
      "<string>"
    ]
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "docs": "<string>",
    "field_errors": {},
    "warnings": [
      "<string>"
    ]
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "docs": "<string>",
    "field_errors": {},
    "warnings": [
      "<string>"
    ]
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "docs": "<string>",
    "field_errors": {},
    "warnings": [
      "<string>"
    ]
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "docs": "<string>",
    "field_errors": {},
    "warnings": [
      "<string>"
    ]
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "docs": "<string>",
    "field_errors": {},
    "warnings": [
      "<string>"
    ]
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "docs": "<string>",
    "field_errors": {},
    "warnings": [
      "<string>"
    ]
  }
}

POST

api

attach

Start a card attachment

curl --request POST \
  --url https://api.agentcard.sh/api/v2/attach \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "user_id": "usr_123"
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({user_id: 'usr_123'})
};

fetch('https://api.agentcard.sh/api/v2/attach', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.agentcard.sh/api/v2/attach"

payload = { "user_id": "usr_123" }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "object": "card_attachment",
  "id": "ca_123",
  "user_id": "usr_123",
  "status": "active",
  "card": {
    "network": "visa",
    "brand": "Visa",
    "last4": "4242",
    "art_url": null
  }
}

{
  "object": "card_attachment",
  "id": "ca_123",
  "user_id": "usr_123",
  "status": "pending",
  "attach_url": "https://agentcard.sh/attach/…",
  "expires_at": "2026-07-23T00:00:00.000Z"
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "docs": "<string>",
    "field_errors": {},
    "warnings": [
      "<string>"
    ]
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "docs": "<string>",
    "field_errors": {},
    "warnings": [
      "<string>"
    ]
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "docs": "<string>",
    "field_errors": {},
    "warnings": [
      "<string>"
    ]
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "docs": "<string>",
    "field_errors": {},
    "warnings": [
      "<string>"
    ]
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "docs": "<string>",
    "field_errors": {},
    "warnings": [
      "<string>"
    ]
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "docs": "<string>",
    "field_errors": {},
    "warnings": [
      "<string>"
    ]
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "docs": "<string>",
    "field_errors": {},
    "warnings": [
      "<string>"
    ]
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "docs": "<string>",
    "field_errors": {},
    "warnings": [
      "<string>"
    ]
  }
}

How it works

You ask for an attachment for a connected user; we return an attach_url. The user opens it and adds their own card in 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. Poll Get the attachment status (or call this endpoint again — with an active attachment it answers 200 with the card instead of starting over). Once active, cards created over MCP charge the attached card directly — no identity verification, no wallet funding. If the response is 422 user_info_required, missing_fields names what to collect first: phone_number via POST /api/v2/wallet/phone/start, consent via POST /api/v2/connect/consent.

Authorizations

Authorization

string

header

required

A platform access token. Get one on the Create an access token endpoint by exchanging your client_id + client_secret, then send it as Authorization: Bearer <token>. Tokens live one hour.

Body

application/json

user_id

string

required

The connected user's id.

Response

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

object

enum<string>

required

Available options:

card_attachment

string

required

The attachment id.

user_id

string

required

status

enum<string>

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.

Available options:

pending,

active,

ineligible

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.

Show child attributes

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.

Refresh the connection Get the attachment status

⌘I

Authentication

Connect

Card attachment

Identity verification

Balance funding

Withdrawals

Platform connect

Start a card attachment

How it works

Authorizations

Body

Response

​How it works

Authorizations

Body

Response

How it works