Skip to content
Linq

API Reference

Libraries

npm install @linqapp/sdk
pip install linq-python
go get -u 'github.com/linq-team/[email protected]'

API Overview

Payment Requests

Request a payment from a recipient over iMessage. You create a payment request, send its checkout_url to the recipient, and they pay with Apple Pay or card. Funds settle directly to your own Stripe account — Linq never holds the money.

How it works

  1. Create a payment request with an amount and currency. You get back a checkout_url and a status of requested.
  2. Send the checkout_url to the recipient as a link message part so it arrives as a tappable card (see Sending the link below).
  3. The recipient pays on the hosted checkout (Apple Pay App Clip on a supported iPhone, web checkout everywhere else).
  4. You receive a payment.succeeded webhook and the request’s status becomes succeeded. Requests you don’t collect eventually expire.

Connected accounts (Stripe Standard, direct charges)

Payments run on Stripe Connect Standard accounts using direct charges: the charge is created on your connected account and you are the merchant of record. That means the money, the payout schedule, the customer relationship, and the compliance surface are all yours — Linq orchestrates the request and the checkout but is never in the funds flow.

Refunds, disputes, and chargebacks are handled by you, in your own Stripe Dashboard. Because charges settle directly to your account, Linq has no custody of the funds and cannot issue refunds or contest disputes on your behalf — and there is no refund/dispute endpoint in this API by design. Use the Stripe Dashboard (or the Stripe API on your own account) for the money lifecycle after a payment succeeds.

Getting set up

Open Agent Pay in your Linq dashboard (https://zero.linqapp.com/organization/payments), click Connect Stripe, and complete Stripe’s onboarding (business details + a bank account). When your account reaches charges_enabled, request creation unlocks; until you connect Stripe, POST /v3/payment_requests returns 403. You can keep collecting even while Stripe finishes background verification.

Subscriptions

Set mode: subscription on POST /v3/payment_requests to start an auto-renewing subscription instead of a one-time charge. Instead of an amount, you pass a price_id — an active recurring Price on your connected Stripe account (create one in your Stripe Dashboard under Product catalog; if you sell through Stripe Payment Links today, reuse the price your link is built from). The recipient pays the first invoice at the same checkout, and their payment method is saved to the subscription for automatic renewals.

The division of labor is deliberate: Linq handles the first payment, your Stripe account handles the rest. The request reaches succeeded when the first invoice is paid; from then on the subscription lives entirely on your connected account. The response’s stripe object gives you the join keys — customer_id and subscription_id — so renewals, plan changes, dunning, and cancellation are managed with your own Stripe Dashboard/API and your own Stripe webhooks. Your metadata is stamped on the Customer and Subscription, so correlating in either direction is trivial. There are no renewal webhooks from Linq by design.

Discounts

Pass a discount with a coupon or promotion code from your connected Stripe account to apply it to the subscription. Create either in your Stripe Dashboard under Product catalog → Coupons; Linq only forwards the id.

{
  "mode": "subscription",
  "price_id": "price_1QAbCdEfGhIjKlMn",
  "discount": {
    "coupon": "7fKCMvBh",
    "label": "50% OFF FIRST MONTH"
  }
}

Stripe applies the coupon and prices the first invoice; the amount we return is that invoice’s amount due, so a $50.00/month price with a 50%-off-first-month coupon comes back as 2500 and the recipient is charged $25.00 at checkout. A coupon that covers the whole first invoice returns amount: 0; checkout shows $0.00 and collects the card for the renewal rather than charging now. Renewals bill at the full price automatically — how long a discount lasts is the coupon’s duration, enforced by Stripe on your account, and Linq never re-prices anything.

Use promotion_code instead of coupon to apply a promotion code by id (promo_..., not the customer-facing code string); pass one or the other, never both.

label is the customer-facing promotion name displayed at checkout instead of the coupon or promotion code ID. The label is displayed exactly as provided, so include important terms such as “FIRST MONTH” or “FIRST 3 MONTHS” when applicable. These terms are not displayed elsewhere on the checkout screen.

If omitted, Stripe uses the coupon’s name as the promotion label.

Free trials

Add trial_period_days (or a fixed trial_end timestamp) to start the subscription with a free trial. The checkout still collects the recipient’s payment method — the pay sheet shows “$0 due today” with the first charge date — and saves it to the subscription; Stripe bills it automatically when the trial ends. The request reaches succeeded when the card is collected, and the response carries trial_end. If the trial would end without a payment method on file, the subscription cancels rather than generating unpayable invoices. Trial lifecycle after checkout (extending, ending early) is managed in your own Stripe account via stripe.subscription_id.

A subscription request you cancel (or that expires unpaid) cancels the incomplete Stripe subscription — nothing lingers on your account.

Pre-created customers

By default each request stands alone: payment mode attaches no Customer, and subscription mode creates a fresh one. If you already manage Customers on your connected account, pass their id as customer_id (cus_...) on create — in payment mode the charge lands on that customer’s payment history, and in subscription mode the subscription is created on them instead of on a new Customer. The id must reference an existing, non-deleted customer on your connected account or the request fails with 400. We never modify a customer you pass — no metadata is stamped on it.

Deliver the checkout_url as a link message part via POST /v3/chats/{chatId}/messages — it renders as a rich card with your branding (title, amount, image) instead of a bare URL, which converts far better. A link part must be the only part in the message. See Rich Link Previews.

On a supported iPhone the link opens an Apple Pay App Clip — a native, no-install checkout sheet. Everywhere else (Android, desktop, iPhones without the App Clip yet) the same URL opens the web checkout, so the link always works. The App Clip experience for your payment links is registered automatically by Linq and refreshed whenever you update your payments branding; a newly registered experience can take up to ~24 hours to activate on Apple’s side, during which links open the web checkout.

Sending it as a card instead

A link part is one way to deliver a request. The other is the agentpay experience, which sends the same request as a native card in Linq’s iMessage app — the amount and reason are drawn in the bubble, and it turns itself into “Paid” in place once the payment succeeds, without a second message.

Send it to POST /v3/chats/{chatId}/messages:

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

checkout_url is the only required field — pass back exactly what POST /v3/payment_requests returned. The amount and reason are read from that request, never from you, so the card can never claim a different figure than the checkout will charge. Optional title and note override the copy only. The link must be one of your own payment requests; another partner’s is rejected.

The trade-off against a link part: a card is an app card, so it is iMessage-only, and recipients without the app see a static version of it. A link works everywhere and is what opens the Apple Pay App Clip. Send whichever suits the conversation — both settle the same payment request and fire the same webhooks.

Webhooks

Subscribe to payment lifecycle events to reconcile server-side rather than polling: payment.succeeded, payment.canceled, and payment.expired. Each event carries the payment request id, amount, currency, and your metadata. See Webhooks.

Create a payment request
POST/v3/payment_requests
Get a payment request
GET/v3/payment_requests/{paymentRequestId}
List payment requests
GET/v3/payment_requests
Cancel a payment request
POST/v3/payment_requests/{paymentRequestId}/cancel

Payment Providers

Let an agent pay on a customer’s behalf with a single-use virtual card. Connect a customer once, then create a payment — a virtual card is minted scoped to that purchase and the card details are handed back for checkout.

Start payment-provider onboarding
POST/v3/payments/providers/{provider}/connect
Get payment-provider status
GET/v3/payments/providers/{provider}

Payment Handles

Let an agent pay on a customer’s behalf with a single-use virtual card. Connect a customer once, then create a payment — a virtual card is minted scoped to that purchase and the card details are handed back for checkout.

Connect a customer handle
POST/v3/payments/handles/{handle}/connect
Submit a customer's one-time code
POST/v3/payments/handles/{handle}/verify
Get a handle's connection status
GET/v3/payments/handles/{handle}/connection
Revoke a handle's connection
DELETE/v3/payments/handles/{handle}/connection

Payments

Let an agent pay on a customer’s behalf with a single-use virtual card. Connect a customer once, then create a payment — a virtual card is minted scoped to that purchase and the card details are handed back for checkout.

Get a payment
GET/v3/payments/{paymentId}
Cancel a payment
POST/v3/payments/{paymentId}/cancel
Get a payment's card-reveal handoff
GET/v3/payments/{paymentId}/credentials

Webhook Events

Webhook Subscriptions allow you to receive real-time notifications when events occur on your account.

Configure webhook endpoints to receive payment and connection lifecycle events.

Failed deliveries (5xx, 429, network errors) are retried with exponential backoff for up to 30 minutes. Each event includes a unique ID for deduplication.

Webhook Headers

All webhook requests include two sets of headers. If you have an existing integration using the X-Webhook-* headers, nothing changes — those headers are still sent on every delivery and work exactly as before. The new webhook-* headers follow the Standard Webhooks specification. You can safely ignore them if your current verification code works and you don’t want to use this convention.

Used by our SDK and any Standard Webhooks library.

HeaderDescription
webhook-idUnique event identifier (use as idempotency key)
webhook-timestampUnix timestamp (seconds) when the webhook was sent
webhook-signatureStandard Webhooks signature (v1,{base64} format)

Legacy Headers (Deprecated)

Still sent on every delivery for backwards compatibility. Existing verification code using these headers continues to work — no changes required.

HeaderDescription
X-Webhook-Event(deprecated) Event type (e.g., message.sent)
X-Webhook-Subscription-ID(deprecated) Webhook subscription ID
X-Webhook-Timestamp(deprecated) Unix timestamp (seconds)
X-Webhook-Signature(deprecated) HMAC-SHA256 signature (hex-encoded)

Signing Secrets

Signing secrets use the Standard Webhooks format: a whsec_ prefix followed by base64-encoded random bytes (e.g., whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw7Jxx2Oll+OE=).

Strip the whsec_ prefix and base64-decode the remainder to get the raw key bytes.

Verifying Webhook Signatures

Webhooks are signed following the Standard Webhooks specification. You can use any Standard Webhooks library to verify signatures, or implement verification manually:

Signed content: {webhook-id}.{webhook-timestamp}.{body}

Verification Steps:

  1. Extract the webhook-id, webhook-timestamp, and webhook-signature headers
  2. Reject if the timestamp is more than 5 minutes old (replay protection)
  3. Get the raw request body bytes (do not parse and re-serialize)
  4. Construct signed content: "{webhook-id}.{webhook-timestamp}.{body}"
  5. Strip the whsec_ prefix from your secret and base64-decode to get key bytes
  6. Compute HMAC-SHA256 using the key bytes over the signed content
  7. Base64-encode the result and compare with the value after v1, in webhook-signature
  8. Use constant-time comparison to prevent timing attacks

Example (Python):

import base64, hmac, hashlib

def verify_webhook(secret, body, headers):
    msg_id = headers['webhook-id']
    timestamp = headers['webhook-timestamp']
    signature = headers['webhook-signature']

    secret_str = secret.removeprefix('whsec_')
    key = base64.b64decode(secret_str)

    signed_content = f"{msg_id}.{timestamp}.{body}"
    expected = base64.b64encode(
        hmac.new(key, signed_content.encode(), hashlib.sha256).digest()
    ).decode()

    for sig in signature.split(' '):
        if sig.startswith('v1,') and hmac.compare_digest(expected, sig[3:]):
            return True
    return False

Example (Node.js):

const crypto = require('crypto');

function verifyWebhook(secret, rawBody, headers) {
  const msgId = headers['webhook-id'];
  const timestamp = headers['webhook-timestamp'];
  const signature = headers['webhook-signature'];

  const secretStr = secret.startsWith('whsec_') ? secret.slice(6) : secret;
  const keyBytes = Buffer.from(secretStr, 'base64');
  const signedContent = `${msgId}.${timestamp}.${rawBody}`;
  const expected = crypto
    .createHmac('sha256', keyBytes)
    .update(signedContent)
    .digest('base64');

  return signature.split(' ').some(sig => {
    if (!sig.startsWith('v1,')) return false;
    try {
      return crypto.timingSafeEqual(
        Buffer.from(expected, 'base64'),
        Buffer.from(sig.slice(3), 'base64')
      );
    } catch { return false; }
  });
}

Security Best Practices:

  • Reject webhooks with timestamps older than 5 minutes to prevent replay attacks
  • Always use constant-time comparison for signature verification
  • Store your signing secret securely (e.g., environment variable, secrets manager)
  • Return a 2xx status code quickly, then process the webhook asynchronously

Webhook Subscriptions

Webhook Subscriptions allow you to receive real-time notifications when events occur on your account.

Configure webhook endpoints to receive payment and connection lifecycle events.

Failed deliveries (5xx, 429, network errors) are retried with exponential backoff for up to 30 minutes. Each event includes a unique ID for deduplication.

Webhook Headers

All webhook requests include two sets of headers. If you have an existing integration using the X-Webhook-* headers, nothing changes — those headers are still sent on every delivery and work exactly as before. The new webhook-* headers follow the Standard Webhooks specification. You can safely ignore them if your current verification code works and you don’t want to use this convention.

Used by our SDK and any Standard Webhooks library.

HeaderDescription
webhook-idUnique event identifier (use as idempotency key)
webhook-timestampUnix timestamp (seconds) when the webhook was sent
webhook-signatureStandard Webhooks signature (v1,{base64} format)

Legacy Headers (Deprecated)

Still sent on every delivery for backwards compatibility. Existing verification code using these headers continues to work — no changes required.

HeaderDescription
X-Webhook-Event(deprecated) Event type (e.g., message.sent)
X-Webhook-Subscription-ID(deprecated) Webhook subscription ID
X-Webhook-Timestamp(deprecated) Unix timestamp (seconds)
X-Webhook-Signature(deprecated) HMAC-SHA256 signature (hex-encoded)

Signing Secrets

Signing secrets use the Standard Webhooks format: a whsec_ prefix followed by base64-encoded random bytes (e.g., whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw7Jxx2Oll+OE=).

Strip the whsec_ prefix and base64-decode the remainder to get the raw key bytes.

Verifying Webhook Signatures

Webhooks are signed following the Standard Webhooks specification. You can use any Standard Webhooks library to verify signatures, or implement verification manually:

Signed content: {webhook-id}.{webhook-timestamp}.{body}

Verification Steps:

  1. Extract the webhook-id, webhook-timestamp, and webhook-signature headers
  2. Reject if the timestamp is more than 5 minutes old (replay protection)
  3. Get the raw request body bytes (do not parse and re-serialize)
  4. Construct signed content: "{webhook-id}.{webhook-timestamp}.{body}"
  5. Strip the whsec_ prefix from your secret and base64-decode to get key bytes
  6. Compute HMAC-SHA256 using the key bytes over the signed content
  7. Base64-encode the result and compare with the value after v1, in webhook-signature
  8. Use constant-time comparison to prevent timing attacks

Example (Python):

import base64, hmac, hashlib

def verify_webhook(secret, body, headers):
    msg_id = headers['webhook-id']
    timestamp = headers['webhook-timestamp']
    signature = headers['webhook-signature']

    secret_str = secret.removeprefix('whsec_')
    key = base64.b64decode(secret_str)

    signed_content = f"{msg_id}.{timestamp}.{body}"
    expected = base64.b64encode(
        hmac.new(key, signed_content.encode(), hashlib.sha256).digest()
    ).decode()

    for sig in signature.split(' '):
        if sig.startswith('v1,') and hmac.compare_digest(expected, sig[3:]):
            return True
    return False

Example (Node.js):

const crypto = require('crypto');

function verifyWebhook(secret, rawBody, headers) {
  const msgId = headers['webhook-id'];
  const timestamp = headers['webhook-timestamp'];
  const signature = headers['webhook-signature'];

  const secretStr = secret.startsWith('whsec_') ? secret.slice(6) : secret;
  const keyBytes = Buffer.from(secretStr, 'base64');
  const signedContent = `${msgId}.${timestamp}.${rawBody}`;
  const expected = crypto
    .createHmac('sha256', keyBytes)
    .update(signedContent)
    .digest('base64');

  return signature.split(' ').some(sig => {
    if (!sig.startsWith('v1,')) return false;
    try {
      return crypto.timingSafeEqual(
        Buffer.from(expected, 'base64'),
        Buffer.from(sig.slice(3), 'base64')
      );
    } catch { return false; }
  });
}

Security Best Practices:

  • Reject webhooks with timestamps older than 5 minutes to prevent replay attacks
  • Always use constant-time comparison for signature verification
  • Store your signing secret securely (e.g., environment variable, secrets manager)
  • Return a 2xx status code quickly, then process the webhook asynchronously
Create a new webhook subscription
POST/v3/webhook-subscriptions
List all webhook subscriptions
GET/v3/webhook-subscriptions
Get a webhook subscription by ID
GET/v3/webhook-subscriptions/{subscriptionId}
Update a webhook subscription
PUT/v3/webhook-subscriptions/{subscriptionId}
Delete a webhook subscription
DELETE/v3/webhook-subscriptions/{subscriptionId}

Webhooks