Card Handoff API

Save a card the person enters in your app to their Layout account. Your server sends it to secure.layout.link, which turns it into a token before Layout sees the request, so Layout never receives the card number.

Send only a card that:

• the person enters in your app, in a flow that shows Layout's consent text, for the purpose of saving it with Layout;
• is theirs, or one the cardholder lets them use;
• goes to the Layout account of that same person.

Never send a card you collected for something else, kept from an earlier purchase, or got from anyone but the person. Do not keep the security code after you send it.

Collect cards with Stripe Elements or another processor? You never see the number, so use card links (POST /v1/users/{userId}/links) instead.

Sandbox

The Card Handoff API is on in sandbox for every application, with nothing to ask for. Use your sk_test_ key and a test card number. A sandbox handoff checks everything a live one does up to the card itself, the person, the consent and the rate limits, and then answers 201 with a stand-in card. Nothing is saved, and nothing is billed.

→ 201
{
  "card": {
    "id": "card_sandbox",
    "brand": "visa",
    "last4": "4242",
    "isDefault": false,
    "createdAt": "2026-11-06T17:02:12.000Z"
  },
  "sandbox": true
}

A sandbox key takes only these numbers. Any other number is 400 invalid_request, “Sandbox keys take test card numbers only.” Never send a real card number to sandbox.

In sandbox every test number succeeds with the same stand-in card; there is no decline path, whichever number you send. Listing a person's cards always answers an empty data, and removing a card always answers 404 not_found.

Send a card

Send the card from your server to secure.layout.link, never to api.layout.link. The person must have verified their number with your application first (see Verify their phone).

POST https://secure.layout.link/v1/users/usr_4b8e9a01c2d3/cards
Authorization: Bearer sk_live_…
Content-Type: application/json

{
  "card": { "number": "4242424242424242", "expMonth": 12, "expYear": 2030, "cvc": "123" },
  "consent": { "method": "checkbox", "textVersion": "2026-11-05", "at": "2026-11-06T17:02:11Z" }
}

→ 201
{
  "card": {
    "id": "card_3bf6b498-b614-4b58-8f04-36c3b2635a3c",
    "brand": "visa",
    "last4": "4242",
    "isDefault": false,
    "createdAt": "2026-11-06T17:02:12.000Z"
  }
}

Put card details only inside card. A card number anywhere else in the body is refused with “Send card details only inside card.” secure.layout.link answers only POST /v1/users/{userId}/cards; list and remove cards on api.layout.link.

The answer never carries the card number, expiry or security code: only id, brand, last4, isDefault and createdAt. Keep id to remove the card later.

brand is Stripe's display brand for the card, in lowercase with underscores: american_express, cartes_bancaires, diners_club, discover, eftpos_australia, interac, jcb, mastercard, union_pay, visa or other. Treat a value you do not know as other. brand and last4 are null when Layout could not read them. Sandbox always answers visa and 4242.

Retrying

This call does not honour Idempotency-Key. A retry after a timeout can save the card a second time, and each save is billed. Before you retry, list the person's cards (below) and send the card again only if it is not there.

What happens to the card

• One per person per application. A new card for the same person replaces your last one. A replacement is a new card saved, and is billed.
• It pays for your orders. An order built through your application bills your card first. It never pays another application's orders unless the person makes it their default.
• It is the person's. Layout shows it to them as added by your application, and they can make it their default or remove it. It never becomes the default on its own, and it does not count toward their plan's card limit.
• Layout tells them. Every saved card sends the person a text, and an email when Layout has one, naming your application and the card's brand and last four.

Consent

Before you send a card, show or read the person Layout's consent text and get their agreement. Report how in consent.

Version 2026-11-05 reads, with its placeholders filled in:

“Save {brand} ending {last4} with Layout to pay for orders you place through {app}. Layout charges this card only when you place an order. You can remove it anytime.”

{app} is your application's name as registered with Layout. Show it in full and do not reword it.

A consent Layout cannot accept is 400 invalid_request, and the message says which part:

• “consent is required: { method, textVersion, at }.”
• “consent.method must be one of checkbox, button, sms_reply, voice.”
• “consent.textVersion must name Layout's consent wording: 2026-11-05.”
• “consent.at must be an ISO 8601 time, when the person agreed.”
• “consent.at is in the future.”
• “consent.at is more than 30 days ago; ask the person again.”
• “consent.at is before this person verified their number with your application; ask them again.”

List and remove cards

Both go to api.layout.link with your secret key, and see only the cards your application handed over, never the rest of the person's wallet.

GET /v1/users/usr_4b8e9a01c2d3/cards

→ 200
{ "data": [ { "id": "card_3bf6b498-b614-4b58-8f04-36c3b2635a3c", "brand": "visa", "last4": "4242", "isDefault": false, "createdAt": "2026-11-06T17:02:12.000Z" } ] }

DELETE /v1/users/usr_4b8e9a01c2d3/cards/card_3bf6b498-b614-4b58-8f04-36c3b2635a3c

→ 200
{ "id": "card_3bf6b498-b614-4b58-8f04-36c3b2635a3c", "removed": true }

When a person asks you to remove their card, or takes back their consent, remove it. A card paying an order still in progress cannot be removed yet: that is 409 card_in_use, so try again when the order finishes. A card id your application did not hand over for this person is 404 not_found. Disconnecting a person from your application removes your cards from their account too.

Errors

Errors have the usual shape. Switch on code. These come from secure.layout.link before the card reaches Layout:

And these from Layout's API:

A key Layout does not accept gets the usual authentication errors; see Errors and status.

Paused for declines

Layout counts your application's live handoffs since the later of 24 hours ago and when live was last turned on for it. Handoffs refused for billing are not counted. Each time a card issuer declines a card, Layout checks that window: at 200 or more declines, or at least 20 handoffs with more than 30% of them declined, it pauses the Card Handoff API for your application until Layout reviews it. While paused, every Card Handoff call answers 404 not_found. Only issuer declines count; a mistyped number, security code or expiry, an expired card, and Layout's own failures do not.

Going live

Live needs production access for your application first (see Going to production). Then:

1. In the console, open App details and choose Go live beside Card Handoff API under Add-ons.
2. Say how your app collects cards and the person's consent, and send the request. Layout emails you when it decides.
3. Once approved, open Billing: add your billing details, sign the agreement, and connect your business checking account.

Live turns on for your application the moment you sign. Live cards are saved once the bank is connected; until then a live handoff answers 402 billing_required. If Layout does not approve, the email and App details say why, and you can ask again.

Pricing

US$0.50 for each card saved in live, billed monthly for the month before by debit from your business checking account. Refused or failed requests, listing and removing cards, and sandbox are free. See layout.link/pricing.

Your account can owe up to US$250 at a time, counting debits from the last 60 days that a bank could still return. At the limit, live saves answer 402 billing_limit_reached until a payment clears.