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

### Parameters

- `params PaymentRequestNewParams`

  - `Amount param.Field[int64]`

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

  - `Currency param.Field[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).

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

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

  - `From param.Field[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 param.Field[map[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 param.Field[PaymentRequestNewParamsMode]`

    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]`

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

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

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

  - `Rail param.Field[PaymentRequestNewParamsRail]`

    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]`

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

  - `TrialPeriodDays param.Field[int64]`

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

  - `IdempotencyKey param.Field[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.

### Returns

- `type PaymentRequest struct{…}`

  - `ID string`

    Unique identifier of the payment request.

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

  - `CheckoutURL string`

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

  - `CreatedAt Time`

  - `Currency string`

  - `Mode PaymentRequestMode`

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

    - `const PaymentRequestModePayment PaymentRequestMode = "payment"`

    - `const PaymentRequestModeSubscription PaymentRequestMode = "subscription"`

  - `Object string`

  - `Status PaymentRequestStatus`

    Lifecycle status of the payment request.

    - `const PaymentRequestStatusRequested PaymentRequestStatus = "requested"`

    - `const PaymentRequestStatusSucceeded PaymentRequestStatus = "succeeded"`

    - `const PaymentRequestStatusCanceled PaymentRequestStatus = "canceled"`

    - `const PaymentRequestStatusExpired PaymentRequestStatus = "expired"`

  - `Description string`

  - `ExpiresAt Time`

    When an unpaid request auto-expires.

  - `Interval PaymentRequestInterval`

    Subscription mode — how often the subscription renews.

    - `const PaymentRequestIntervalDay PaymentRequestInterval = "day"`

    - `const PaymentRequestIntervalWeek PaymentRequestInterval = "week"`

    - `const PaymentRequestIntervalMonth PaymentRequestInterval = "month"`

    - `const PaymentRequestIntervalYear PaymentRequestInterval = "year"`

  - `IntervalCount int64`

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

  - `Metadata map[string, string]`

  - `Natural PaymentRequestNatural`

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

    - `PaymentRequestID string`

      The Natural payment request (`prq_...`).

    - `TransactionID string`

      The settled transaction (`txn_...`).

  - `PaidAt Time`

    When the request was paid. Absent until it succeeds.

  - `PriceID string`

    Subscription mode — the recurring price this request subscribes to.

  - `Quantity int64`

    Subscription mode — units of the price subscribed to.

  - `Rail PaymentRequestRail`

    The rail this request settled on.

    - `const PaymentRequestRailStripe PaymentRequestRail = "stripe"`

    - `const PaymentRequestRailNatural PaymentRequestRail = "natural"`

  - `Stripe PaymentRequestStripe`

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

    - `PaymentIntentID string`

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

    - `SubscriptionID string`

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

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

  - `UpdatedAt Time`

### Example

```go
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)
}
```

#### Response

```json
{
  "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"
}
```