Sending payment links

Every payment request returns a checkout_url. How you deliver it decides how well it converts.

Deliver the checkout_url over iMessage as a link message part — not as plain text. A link part renders a rich card showing your display name, the amount, and your brand image, which converts far better than a bare URL.

Post it to an existing chat with POST /v3/chats/{chatId}/messages:

{
  "message": {
    "parts": [
      { "type": "link", "value": "https://zero.linqapp.com/pay/acme?session=tok_..." }
    ]
  }
}

A link part must be the only part in the message — it can’t be combined with text or media. See Rich Link Previews for the full behavior.

:::note When you start a new chat with POST /v3/chats, the first message can’t contain a link. Send a short intro message to open the chat, then send the payment link as a follow-up with the returned chat id. :::

The other option is the agentpay experience — the same request delivered as a native card inside Linq’s iMessage app, rather than as a link out to a checkout page. The amount and reason are drawn in the bubble, and once the payment succeeds the card turns itself into “Paid” in place, without you sending a second message.

{
  "message": {
    "experience": {
      "name": "agentpay",
      "action": "request_payment",
      "params": { "checkout_url": "https://zero.linqapp.com/pay/acme?session=tok_..." }
    }
  }
}

checkout_url is the only field you have to send — pass back exactly what the payment request returned. The amount and reason are read from that request rather than from you, so a card can never show a figure the checkout won’t actually charge. Optional title and note override the copy only.

A link is the safer default when you don’t know what the recipient is on, and it’s the only route to the App Clip. A card is the better experience inside an ongoing iMessage conversation, especially when you want the bubble itself to reflect that it’s been paid. Both settle the same payment request and fire the same webhooks.

See Experiences for the full invocation rules.

The checkout_url works everywhere, and picks the best experience for the recipient automatically:

• Supported iPhone → the link opens an Apple Pay App Clip: a native, no-install checkout sheet the recipient can pay in a couple of taps.
• Everywhere else (Android, desktop, iPhones where the App Clip isn’t available yet) → the same URL opens the web checkout.

You don’t choose or configure this — send the one checkout_url and the recipient gets the right one.

Linq registers the Apple App Clip experience for your payment links automatically, and refreshes it whenever you update your payments branding (display name or brand image). Two timing details worth knowing:

• A newly registered experience can take up to ~24 hours to activate on Apple’s side. During that window your links open the web checkout — nothing is broken, and payments still go through.
• After you change your branding, Apple similarly takes time to propagate the refreshed card. The link keeps working throughout.

Because the web checkout is always available as the fallback, you never have to wait on Apple to start collecting — the App Clip simply upgrades the experience as it becomes available.

• A request is payable until its expires_at. After that it moves to expired and the link no longer accepts payment — create a new request if you need to.
• To retract a request before it’s paid, call POST /v3/payment_requests/{paymentRequestId}/cancel. Cancelling a request that’s already succeeded or otherwise terminal returns 409.

• Payments overview
• Connected accounts — one-time Stripe setup.
• Payment webhooks