Card links for every app

Every application can now mint a card link for a person it provisioned and verified. It is how that person adds a card.

What changed

• POST /v1/users/:id/links with { "purpose": "card" }, and optionally a returnUrl and a state, answers 201 with a url on layout.link/h/ and its expiresAt. The link works once and must be opened within 15 minutes.
• The page. It shows your application's name and logo, says your application partners with Layout and never sees the card, takes a card, Apple Pay or Google Pay, and asks for no Layout sign-in.
• Return URLs. Register them on App details in the console: https, your app's own scheme, or localhost for sandbox. The page sends the person back with status=card_added or status=canceled, and your state.
• A card link only adds a card. On an account that already holds all the cards it can, it replaces only a card one of your own card links added. Otherwise the page tells the person their account is full, nothing is saved, and going back returns status=canceled. It never removes a card the person or another application added.
• No url on card_required. For a person you provisioned, a build that fails with no_card or card_not_orderable, and a confirm that answers build_only with card_required, carry no url. Mint a card link instead.

Update 2026-10-21: A card link adds only on an account the person signs in to. On an account nobody signs in to, which is every account a verify made, a card link on a full account replaces the default card, and the page names that card before they save. See What the person sees.

POST /v1/users/usr_4b8e9a01c2d3/links
{ "purpose": "card", "returnUrl": "com.acme.assistant:/layout/card", "state": "c1f9e2" }

→ 201
{ "url": "https://layout.link/h/3q2Xw7…", "expiresAt": "2026-10-21T17:15:00.000Z", "purpose": "card" }

Why it matters

A person you provisioned has no Layout sign-in to use, so a page that asked for one stopped them. The card link asks for nothing but the card, and brings them back to your app.

What to do

Register a return URL in the console. When Layout asks for a card, mint a link and open it: as a sheet in an iOS app, in ASWebAuthenticationSession or SFSafariViewController, or as a link in a chat or text. See Card links.

Breaking changes

Code that sent failure.next.url or error.next.url on card_required to a person you provisioned gets no url now. Mint a card link for them instead.

All changes