> ## Documentation Index
> Fetch the complete documentation index at: https://docs.payreque.st/llms.txt
> Use this file to discover all available pages before exploring further.

# Payment Links & Payments

> Programmatically create payment links and reconcile payments via the API

# Payment Links & Payments

Use these endpoints to generate fixed-amount payment links on the fly and query incoming payments for reconciliation — for example, per-user or per-reference billing flows.

## Create a Payment Link

Generates a shareable payment link (Smart Link) with a fixed amount and a custom description you can use as a reference when reconciling.

<ParamField header="Authorization" type="string" required>
  Bearer token with `billing.write` scope
</ParamField>

```bash theme={null}
POST /api/v1/payment-links
```

### Request Body

<ParamField body="description" type="string" required>
  Your internal reference, shown on the payment page and included in all webhook payloads and payment records. Example: `JMIT-githubuser`
</ParamField>

<ParamField body="amount" type="number" required>
  Fixed payment amount in euros (decimal). Example: `49.00`
</ParamField>

<ParamField body="currency" type="string" default="EUR">
  3-letter ISO currency code. Defaults to `EUR`.
</ParamField>

### Request Example

```bash theme={null}
curl -X POST "https://payrequest.app/api/v1/payment-links" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "JMIT-githubuser",
    "amount": 49.00
  }'
```

### Response

```json theme={null}
{
  "success": true,
  "data": {
    "id": 42,
    "url": "https://payrequest.me/jmit/jmit-githubuser",
    "description": "JMIT-githubuser",
    "amount": 49.00,
    "currency": "EUR",
    "created_at": "2026-05-30T12:00:00+02:00"
  }
}
```

<Note>
  The URL slug is automatically derived from your `description` (e.g. `JMIT-githubuser` → `jmit-githubuser`). If a link with that slug already exists, a numeric suffix is appended (`jmit-githubuser-2`).
</Note>

***

## List Payment Links

Returns a paginated list of all your payment links.

<ParamField header="Authorization" type="string" required>
  Bearer token with `billing.read` scope
</ParamField>

<ParamField query="per_page" type="integer" default="25">
  Number of results per page (max 100)
</ParamField>

```bash theme={null}
GET /api/v1/payment-links
```

### Request Example

```bash theme={null}
curl "https://payrequest.app/api/v1/payment-links?per_page=10" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

### Response

```json theme={null}
{
  "success": true,
  "data": {
    "current_page": 1,
    "data": [
      {
        "id": 42,
        "url": "https://payrequest.me/jmit/jmit-githubuser",
        "description": "JMIT-githubuser",
        "amount": 49.00,
        "currency": "EUR",
        "payments_count": 1,
        "revenue": 49.00,
        "is_active": true,
        "created_at": "2026-05-30T12:00:00+02:00"
      }
    ],
    "per_page": 25,
    "total": 1
  }
}
```

***

## List Payments

Query incoming payments for reconciliation. Filter by `description` to find all payments tied to a specific reference.

<ParamField header="Authorization" type="string" required>
  Bearer token with `billing.read` scope
</ParamField>

<ParamField query="description" type="string">
  Filter payments by description (case-insensitive partial match). Example: `JMIT-githubuser`
</ParamField>

<ParamField query="status" type="string">
  Filter by status: `paid`, `open`, `pending`, or `failed`
</ParamField>

<ParamField query="from" type="date">
  Start date filter (YYYY-MM-DD)
</ParamField>

<ParamField query="to" type="date">
  End date filter (YYYY-MM-DD)
</ParamField>

<ParamField query="per_page" type="integer" default="25">
  Number of results per page (max 100)
</ParamField>

```bash theme={null}
GET /api/v1/payments
```

### Request Example

```bash theme={null}
curl "https://payrequest.app/api/v1/payments?description=JMIT-githubuser&status=paid" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

### Response

```json theme={null}
{
  "success": true,
  "data": {
    "current_page": 1,
    "data": [
      {
        "id": 1234,
        "description": "JMIT-githubuser",
        "amount": 49.00,
        "currency": "EUR",
        "status": "paid",
        "payment_method": "ideal",
        "payment_link_id": 42,
        "payment_link_url": "https://payrequest.me/jmit/jmit-githubuser",
        "reference": "tr_abc123",
        "paid_at": "2026-05-30T11:59:45+02:00",
        "created_at": "2026-05-30T11:58:00+02:00",
        "customer": {
          "id": 99,
          "name": "Jane Doe",
          "email": "jane@example.com"
        }
      }
    ],
    "per_page": 25,
    "total": 1
  }
}
```

***

## Reconciliation workflow

A typical programmatic billing flow using these endpoints:

1. **Create a payment link** with the user's identifier as `description` (e.g. `JMIT-githubuser`)
2. **Send the `url`** to your customer via email or embed it in your app
3. **Receive a webhook** (`payment.succeeded`) with the `description` and `payment_link_id` when payment arrives — see [Webhooks](/api/webhooks)
4. **Or poll** `GET /v1/payments?description=JMIT-githubuser&status=paid` to reconcile on demand