Payments

Create a payment request

Creates a payment request and returns a checkout_url the recipient opens to pay with Apple Pay or card. Funds settle directly to your connected Stripe account. A payment request is independent of any chat; to associate one with a chat for your records, store the chat id in metadata. Requires your connected account to be charges_enabled (returns 403 otherwise).

Set mode: subscription with a recurring price_id from your connected Stripe account to start an auto-renewing subscription instead of a one-time charge — the recipient pays the first invoice at checkout and the response's stripe object carries the customer and subscription ids for the ongoing lifecycle in your own Stripe account. See the Subscriptions section of the tag overview.

In either mode, pass customer_id to attach the request to an existing Customer on your connected account instead of creating a new one — see Pre-created customers in the tag overview.

post/v3/payment_requests

Request

  • Base URL: https://api.linqapp.com/api/partner
  • URL: https://api.linqapp.com/api/partner/v3/payment_requests
  • Auth: HTTP bearer

Headers

Idempotency-Keystring
Example:pr-abc123xyz

Optional idempotency key (max 200 characters). Reuse the same key to safely retry without creating a second payment request. Reusing a key with different request parameters returns 409.

Request body

mode'payment' | 'subscription'

payment (default) collects a one-time charge for amount + currency. subscription starts an auto-renewing subscription from a recurring price_id on your connected Stripe account: the recipient pays the first invoice at checkout and Stripe renews it automatically from then on.

amountinteger

Amount to charge, in the currency's minor units (e.g. cents). Must be at least the payment provider's minimum (50 for usd). Required in payment mode; must be omitted in subscription mode (the amount comes from the price).

currencystring

Three-letter ISO 4217 currency code. Only usd is currently supported. Required in payment mode; must be omitted in subscription mode (the currency comes from the price).

price_idstring

Subscription mode only (required there): id of an active recurring Price on your connected Stripe account (price_...). If you sell through Stripe Payment Links today, pass the same price the link was built from to get the native iMessage checkout for it.

quantityinteger

Subscription mode only — units of the price to subscribe to.

customer_idstring

Optional id of an existing Customer on your connected Stripe account (cus_...) to attach this request to, instead of a new Customer being created. In payment mode the charge lands on that customer's payment history; in subscription mode the subscription is created on them. The customer must exist (and not be deleted) on your connected account.

trial_period_daysinteger

Subscription mode only — start with a free trial of this many days. The recipient's card is still collected at checkout (Apple Pay or card), saved to the subscription, and first charged when the trial ends. Mutually exclusive with trial_end.

trial_endstring date-time

Subscription mode only — end the free trial at a fixed timestamp (must be in the future) instead of a day count. Mutually exclusive with trial_period_days.

descriptionstring

Optional description shown to the recipient at checkout.

metadataobject

Optional key/value metadata (up to 49 keys) echoed back on retrieval and on payment.* webhooks, and stamped on the Stripe objects we create on your connected account (the PaymentIntent, and in subscription mode the Subscription and any Customer created for you — a customer you pass via customer_id is never modified) — use it to correlate a request with your own records (e.g. a chat id). Keys starting with linq_ are reserved.

rail'stripe' | 'natural'

Payment rail. stripe (default) is the direct-charge flow that settles to your connected Stripe account. natural collects through the Natural custodial wallet; it requires from + payer_handle and that your organization has completed Natural merchant onboarding.

fromstring

Required for rail: natural. The line the request is sent from, in E.164 format. Must be a phone number your organization owns.

payer_handlestring

Required for rail: natural. The payer to bill, in E.164 format.

Example request

{
  "amount": 497,
  "currency": "usd",
  "price_id": "price_1QAbCdEfGhIjKlMn",
  "customer_id": "cus_QAbCdEfGhIjKlMn",
  "trial_period_days": 14,
  "discount": {
    "coupon": "7fKCMvBh",
    "promotion_code": "promo_1QAbCdEfGhIjKlMn",
    "label": "15% OFF FIRST 3 MONTHS"
  },
  "description": "Session with Ava",
  "from": "+12025550123",
  "payer_handle": "+12025550199"
}

Response

Payment request created

idstring uuid required

Unique identifier of the payment request.

objectstring required
status'requested' | 'succeeded' | 'canceled' | 'expired' required

Lifecycle status of the payment request.

mode'payment' | 'subscription' required

Whether this request collects a one-time charge or starts a subscription.

amountinteger required

What the recipient is charged at checkout, in the currency's minor units. In subscription mode this is the first invoice's amount due — all items after any discounts are applied — so a discount that covers the whole invoice returns 0 and checkout shows $0.00.

currencystring required
price_idstring

Subscription mode — the recurring price this request subscribes to.

interval'day' | 'week' | 'month' | 'year'

Subscription mode — how often the subscription renews.

interval_countinteger

Subscription mode — intervals per renewal (e.g. 3 + month = quarterly).

quantityinteger

Subscription mode — units of the price subscribed to.

trial_endstring date-time

Subscription mode — when the free trial ends and the first charge happens. Present only on trial requests; paid_at/succeeded mean the payment method was collected (no funds move until this time).

descriptionstring
metadataobject
rail'stripe' | 'natural'

The rail this request settled on.

checkout_urlstring required

URL the recipient opens to pay: https://zero.linqapp.com/pay/{slug}?session=..., where {slug} is your partner checkout slug.

created_atstring date-time required
updated_atstring date-time
expires_atstring date-time

When an unpaid request auto-expires.

paid_atstring date-time

When the request was paid. Absent until it succeeds.

Example response

{
  "object": "payment_request",
  "amount": 497,
  "currency": "usd",
  "discount": {
    "coupon": "LAUNCH50",
    "promotion_code": "promo_1QAbCdEfGhIjKlMn",
    "label": "15 OFF FIRST MONTH"
  },
  "stripe": {
    "payment_intent_id": "pi_3QAbCdEfGhIjKlMn",
    "customer_id": "cus_QAbCdEfGhIjKlMn",
    "subscription_id": "sub_1QAbCdEfGhIjKlMn"
  },
  "checkout_url": "https://zero.linqapp.com/pay/tomo?session=tok_abc123"
}

Changes

No recorded changes to this operation across all 1 revision of this API.