Create a payment request

client.PaymentRequests.New(ctx, params) (*PaymentRequest, error)

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 PaymentRequestNewParams

Amount param.Field[int64]Optional

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 param.Field[string]Optional

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

CustomerID param.Field[string]Optional

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 param.Field[string]Optional

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

maxLength1000

From param.Field[string]Optional

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 param.Field[map[string, string]]Optional

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 param.Field[PaymentRequestNewParamsMode]Optional

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.

const PaymentRequestNewParamsModePayment PaymentRequestNewParamsMode = "payment"

const PaymentRequestNewParamsModeSubscription PaymentRequestNewParamsMode = "subscription"

PayerHandle param.Field[string]Optional

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

PriceID param.Field[string]Optional

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 param.Field[int64]Optional

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

formatint64

minimum1

maximum999

Rail param.Field[PaymentRequestNewParamsRail]Optional

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.

const PaymentRequestNewParamsRailStripe PaymentRequestNewParamsRail = "stripe"

const PaymentRequestNewParamsRailNatural PaymentRequestNewParamsRail = "natural"

TrialEnd param.Field[Time]Optional

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

TrialPeriodDays param.Field[int64]Optional

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 param.Field[string]Optional

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

type PaymentRequest struct{…}

ID string

Unique identifier of the payment request.

formatuuid

Amount int64

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

CheckoutURL string

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

CreatedAt Time

formatdate-time

Currency string

Mode PaymentRequestMode

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

One of the following:

const PaymentRequestModePayment PaymentRequestMode = "payment"

const PaymentRequestModeSubscription PaymentRequestMode = "subscription"

Object string

Status PaymentRequestStatus

Lifecycle status of the payment request.

One of the following:

const PaymentRequestStatusRequested PaymentRequestStatus = "requested"

const PaymentRequestStatusSucceeded PaymentRequestStatus = "succeeded"

const PaymentRequestStatusCanceled PaymentRequestStatus = "canceled"

const PaymentRequestStatusExpired PaymentRequestStatus = "expired"

Description stringOptional

ExpiresAt TimeOptional

When an unpaid request auto-expires.

formatdate-time

Interval PaymentRequestIntervalOptional

Subscription mode — how often the subscription renews.

One of the following:

const PaymentRequestIntervalDay PaymentRequestInterval = "day"

const PaymentRequestIntervalWeek PaymentRequestInterval = "week"

const PaymentRequestIntervalMonth PaymentRequestInterval = "month"

const PaymentRequestIntervalYear PaymentRequestInterval = "year"

IntervalCount int64Optional

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

formatint64

Metadata map[string, string]Optional

Natural PaymentRequestNaturalOptional

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

PaymentRequestID stringOptional

The Natural payment request (prq_...).

TransactionID stringOptional

The settled transaction (txn_...).

PaidAt TimeOptional

When the request was paid. Absent until it succeeds.

formatdate-time

PriceID stringOptional

Subscription mode — the recurring price this request subscribes to.

Quantity int64Optional

Subscription mode — units of the price subscribed to.

formatint64

Rail PaymentRequestRailOptional

The rail this request settled on.

One of the following:

const PaymentRequestRailStripe PaymentRequestRail = "stripe"

const PaymentRequestRailNatural PaymentRequestRail = "natural"

Stripe PaymentRequestStripeOptional

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.

CustomerID stringOptional

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.

PaymentIntentID stringOptional

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

SubscriptionID stringOptional

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

TrialEnd TimeOptional

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

UpdatedAt TimeOptional

formatdate-time

Create a payment request

package main

import (
  "context"
  "fmt"

  "github.com/linq-team/linq-go"
  "github.com/linq-team/linq-go/option"
)

func main() {
  client := linqgo.NewClient(
    option.WithAPIKey("My API Key"),
  )
  paymentRequest, err := client.PaymentRequests.New(context.TODO(), linqgo.PaymentRequestNewParams{
    Amount: linqgo.Int(497),
    Currency: linqgo.String("usd"),
    Description: linqgo.String("Coffee with Ava"),
    Metadata: map[string]string{
    "order_id": "order_8675309",
    },
  })
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", 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
}