Skip to content
API Docs
Get started
API Reference
Payment Requests

Create a payment request

client.paymentRequests.create(PaymentRequestCreateParams { amount, currency, customer_id, 11 more } params, RequestOptionsoptions?): PaymentRequest { id, amount, checkout_url, 18 more }
POST/v3/payment_requests

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.

ParametersExpand Collapse
params: PaymentRequestCreateParams { amount, currency, customer_id, 11 more }
amount?: number

Body param: 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).

formatint64
minimum50
currency?: string

Body param: 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).

customer_id?: string

Body param: 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.

description?: string

Body param: Optional description shown to the recipient at checkout.

maxLength1000
from?: string

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

metadata?: Record<string, string>

Body param: 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.

mode?: "payment" | "subscription"

Body param: 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.

One of the following:
"payment"
"subscription"
payer_handle?: string

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

price_id?: string

Body param: 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.

quantity?: number

Body param: Subscription mode only — units of the price to subscribe to.

formatint64
minimum1
maximum999
rail?: "stripe" | "natural"

Body param: 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.

One of the following:
"stripe"
"natural"
trial_end?: string

Body param: 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.

formatdate-time
trial_period_days?: number

Body param: 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.

formatint64
minimum1
maximum730
idempotencyKey?: string

Header param: 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.

maxLength200
ReturnsExpand Collapse
PaymentRequest { id, amount, checkout_url, 18 more }
id: string

Unique identifier of the payment request.

formatuuid
amount: number

Amount in the currency’s minor units. In subscription mode this is the recurring amount (price × quantity) the recipient pays per interval, starting at checkout.

formatint64
checkout_url: string

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

created_at: string
formatdate-time
currency: string
mode: "payment" | "subscription"

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

One of the following:
"payment"
"subscription"
object: string
status: "requested" | "succeeded" | "canceled" | "expired"

Lifecycle status of the payment request.

One of the following:
"requested"
"succeeded"
"canceled"
"expired"
description?: string
expires_at?: string

When an unpaid request auto-expires.

formatdate-time
interval?: "day" | "week" | "month" | "year"

Subscription mode — how often the subscription renews.

One of the following:
"day"
"week"
"month"
"year"
interval_count?: number

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

formatint64
metadata?: Record<string, string>
natural?: Natural { payment_request_id, transaction_id }

Natural-rail join keys, present when rail: natural.

payment_request_id?: string

The Natural payment request (prq_...).

transaction_id?: string

The settled transaction (txn_...).

price_id?: string

Subscription mode — the recurring price this request subscribes to.

quantity?: number

Subscription mode — units of the price subscribed to.

formatint64
rail?: "stripe" | "natural"

The rail this request settled on.

One of the following:
"stripe"
"natural"
stripe?: Stripe { customer_id, payment_intent_id, subscription_id }

Ids of the Stripe objects created on your connected account — your join keys into your own Stripe Dashboard, webhooks, and API. After a subscription’s first payment succeeds, its ongoing lifecycle (renewals, plan changes, cancellation) is managed in your Stripe account using subscription_id.

customer_id?: string

The Customer this request is attached to (cus_...). Always set in subscription mode (created for you unless you passed customer_id); set in payment mode only when you passed one.

payment_intent_id?: string

The PaymentIntent collected at checkout (pi_...).

subscription_id?: string

Subscription mode — the Subscription (sub_...).

trial_end?: string

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).

formatdate-time
updated_at?: string
formatdate-time

Create a payment request

import LinqAPIV3 from '@linqapp/sdk';

const client = new LinqAPIV3({
  apiKey: process.env['LINQ_API_V3_API_KEY'], // This is the default and can be omitted
});

const paymentRequest = await client.paymentRequests.create({
  amount: 497,
  currency: 'usd',
  description: 'Coffee with Ava',
  metadata: { order_id: 'order_8675309' },
});

console.log(paymentRequest.id);
{
  "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
  "amount": 497,
  "checkout_url": "https://zero.linqapp.com/pay/tomo?session=tok_abc123",
  "created_at": "2019-12-27T18:11:19.117Z",
  "currency": "usd",
  "mode": "payment",
  "object": "payment_request",
  "status": "requested",
  "description": "description",
  "expires_at": "2019-12-27T18:11:19.117Z",
  "interval": "day",
  "interval_count": 0,
  "metadata": {
    "foo": "string"
  },
  "natural": {
    "payment_request_id": "payment_request_id",
    "transaction_id": "transaction_id"
  },
  "paid_at": "2019-12-27T18:11:19.117Z",
  "price_id": "price_id",
  "quantity": 0,
  "rail": "stripe",
  "stripe": {
    "customer_id": "cus_QAbCdEfGhIjKlMn",
    "payment_intent_id": "pi_3QAbCdEfGhIjKlMn",
    "subscription_id": "sub_1QAbCdEfGhIjKlMn"
  },
  "trial_end": "2019-12-27T18:11:19.117Z",
  "updated_at": "2019-12-27T18:11:19.117Z"
}
{
  "error": {
    "status": 400,
    "code": 1002,
    "message": "Phone number must be in E.164 format",
    "doc_url": "https://docs.linqapp.com/error/codes/1xxx/1002/"
  },
  "success": false
}
{
  "error": {
    "status": 401,
    "code": 2004,
    "message": "Unauthorized - missing or invalid authentication token",
    "doc_url": "https://docs.linqapp.com/error/codes/2xxx/2004/"
  },
  "success": false
}
{
  "error": {
    "status": 403,
    "code": 2005,
    "message": "Access denied - insufficient permissions for this resource",
    "doc_url": "https://docs.linqapp.com/error/codes/2xxx/2005/"
  },
  "success": false
}
{
  "error": {
    "status": 409,
    "code": 2013,
    "message": "This chat is unavailable",
    "doc_url": "https://docs.linqapp.com/error/codes/2xxx/2013/"
  },
  "success": false
}
{
  "error": {
    "status": 500,
    "code": 3006,
    "message": "Internal server error",
    "doc_url": "https://docs.linqapp.com/error/codes/3xxx/3006/"
  },
  "success": false
}
Returns Examples
{
  "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
  "amount": 497,
  "checkout_url": "https://zero.linqapp.com/pay/tomo?session=tok_abc123",
  "created_at": "2019-12-27T18:11:19.117Z",
  "currency": "usd",
  "mode": "payment",
  "object": "payment_request",
  "status": "requested",
  "description": "description",
  "expires_at": "2019-12-27T18:11:19.117Z",
  "interval": "day",
  "interval_count": 0,
  "metadata": {
    "foo": "string"
  },
  "natural": {
    "payment_request_id": "payment_request_id",
    "transaction_id": "transaction_id"
  },
  "paid_at": "2019-12-27T18:11:19.117Z",
  "price_id": "price_id",
  "quantity": 0,
  "rail": "stripe",
  "stripe": {
    "customer_id": "cus_QAbCdEfGhIjKlMn",
    "payment_intent_id": "pi_3QAbCdEfGhIjKlMn",
    "subscription_id": "sub_1QAbCdEfGhIjKlMn"
  },
  "trial_end": "2019-12-27T18:11:19.117Z",
  "updated_at": "2019-12-27T18:11:19.117Z"
}
{
  "error": {
    "status": 400,
    "code": 1002,
    "message": "Phone number must be in E.164 format",
    "doc_url": "https://docs.linqapp.com/error/codes/1xxx/1002/"
  },
  "success": false
}
{
  "error": {
    "status": 401,
    "code": 2004,
    "message": "Unauthorized - missing or invalid authentication token",
    "doc_url": "https://docs.linqapp.com/error/codes/2xxx/2004/"
  },
  "success": false
}
{
  "error": {
    "status": 403,
    "code": 2005,
    "message": "Access denied - insufficient permissions for this resource",
    "doc_url": "https://docs.linqapp.com/error/codes/2xxx/2005/"
  },
  "success": false
}
{
  "error": {
    "status": 409,
    "code": 2013,
    "message": "This chat is unavailable",
    "doc_url": "https://docs.linqapp.com/error/codes/2xxx/2013/"
  },
  "success": false
}
{
  "error": {
    "status": 500,
    "code": 3006,
    "message": "Internal server error",
    "doc_url": "https://docs.linqapp.com/error/codes/3xxx/3006/"
  },
  "success": false
}
© 2026 Linq, Inc. · linqapp.com