Create a payment request

payment_requests.create() -> PaymentRequest

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

amount: Optional[int]

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: Optional[str]

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: Optional[str]

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: Optional[str]

Optional description shown to the recipient at checkout.

maxLength1000

from_: Optional[str]

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

metadata: Optional[Dict[str, str]]

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: Optional[Literal["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.

One of the following:

"payment"

"subscription"

payer_handle: Optional[str]

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

price_id: Optional[str]

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: Optional[int]

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

formatint64

minimum1

maximum999

rail: Optional[Literal["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.

One of the following:

"stripe"

"natural"

trial_end: Optional[Union[str, datetime]]

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: Optional[int]

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

idempotency_key: Optional[str]

maxLength200

ReturnsExpand Collapse

class PaymentRequest: …

id: str

Unique identifier of the payment request.

formatuuid

amount: int

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: str

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

created_at: datetime

formatdate-time

currency: str

mode: Literal["payment", "subscription"]

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

One of the following:

"payment"

"subscription"

object: str

status: Literal["requested", "succeeded", "canceled", "expired"]

Lifecycle status of the payment request.

One of the following:

"requested"

"succeeded"

"canceled"

"expired"

description: Optional[str]

expires_at: Optional[datetime]

When an unpaid request auto-expires.

formatdate-time

interval: Optional[Literal["day", "week", "month", "year"]]

Subscription mode — how often the subscription renews.

One of the following:

"day"

"week"

"month"

"year"

interval_count: Optional[int]

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

formatint64

metadata: Optional[Dict[str, str]]

natural: Optional[Natural]

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

payment_request_id: Optional[str]

The Natural payment request (prq_...).

transaction_id: Optional[str]

The settled transaction (txn_...).

paid_at: Optional[datetime]

When the request was paid. Absent until it succeeds.

formatdate-time

price_id: Optional[str]

Subscription mode — the recurring price this request subscribes to.

quantity: Optional[int]

Subscription mode — units of the price subscribed to.

formatint64

rail: Optional[Literal["stripe", "natural"]]

The rail this request settled on.

One of the following:

"stripe"

"natural"

stripe: Optional[Stripe]

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: Optional[str]

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: Optional[str]

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

subscription_id: Optional[str]

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

trial_end: Optional[datetime]

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: Optional[datetime]

formatdate-time

Create a payment request

import os
from linq import LinqAPIV3

client = LinqAPIV3(
    api_key=os.environ.get("LINQ_API_V3_API_KEY"),  # This is the default and can be omitted
)
payment_request = client.payment_requests.create(
    amount=497,
    currency="usd",
    description="Coffee with Ava",
    metadata={
        "order_id": "order_8675309"
    },
)
print(payment_request.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
}