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.

A second 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.

The third option is an app_clip part: the same checkout link delivered as an Apple Pay card with an Open button, so the recipient goes straight into the App Clip checkout sheet instead of tapping through a link preview.

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

As with agentpay, the link is the only field you send. The merchant name, amount, description and image are composed by Linq from the checkout session itself — the same content the checkout page already shows — so the card can’t display a figure the checkout won’t charge.

An app_clip part must be the only part in the message.

A link is the safer default when you don’t know what the recipient is on. An agentpay card is the better experience inside an ongoing iMessage conversation, especially when you want the bubble itself to reflect that it’s been paid. An app_clip part is the shortest path to payment for a recipient you already know is on iMessage — it removes a tap versus the link, at the cost of having no fallback. All three 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