## List payment requests

`client.PaymentRequests.List(ctx, query) (*PaymentRequestListResponse, error)`

**get** `/v3/payment_requests`

Lists your payment requests, newest first, for reconciliation. Paginate
with `limit` + `offset`; `has_more` indicates whether another page exists.

### Parameters

- `query PaymentRequestListParams`

  - `Limit param.Field[int64]`

    Max results to return (default 20, max 100).

  - `Offset param.Field[int64]`

    Number of results to skip.

  - `Status param.Field[PaymentRequestListParamsStatus]`

    Filter by lifecycle status.

    - `const PaymentRequestListParamsStatusRequested PaymentRequestListParamsStatus = "requested"`

    - `const PaymentRequestListParamsStatusAuthorized PaymentRequestListParamsStatus = "authorized"`

    - `const PaymentRequestListParamsStatusSucceeded PaymentRequestListParamsStatus = "succeeded"`

    - `const PaymentRequestListParamsStatusCanceled PaymentRequestListParamsStatus = "canceled"`

    - `const PaymentRequestListParamsStatusExpired PaymentRequestListParamsStatus = "expired"`

    - `const PaymentRequestListParamsStatusDeclined PaymentRequestListParamsStatus = "declined"`

### Returns

- `type PaymentRequestListResponse struct{…}`

  - `Data []PaymentRequest`

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

  - `HasMore bool`

    Whether more results exist beyond this page.

  - `Object PaymentRequestListResponseObject`

    - `const PaymentRequestListResponseObjectList PaymentRequestListResponseObject = "list"`

### 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"),
  )
  paymentRequests, err := client.PaymentRequests.List(context.TODO(), linqgo.PaymentRequestListParams{

  })
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", paymentRequests.Data)
}
```

#### Response

```json
{
  "data": [
    {
      "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"
    }
  ],
  "has_more": true,
  "object": "list"
}
```