v1

latestOpenAPI 3.1.02026-07-26261466.6 KB

Card attachment

Start a card attachment

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.

post/api/v2/attach

Request body

user_idstring required

The connected user's id.

Response

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

object'card_attachment' required

idstring required

The attachment id.

user_idstring 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_urlstring

The hosted link the user opens to add their card. Present only on the start response.

expires_atstring date-time

When the attach link expires (48 hours). Present only on the start response.

reasonstring

Why the card cannot be attached (e.g. issuer_excluded, commercial_card). Present when status is ineligible.

messagestring

Human-readable guidance. Present when status is ineligible.