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

# Create Payment Link

> Generate a payment link for one-time or recurring payments

# Create Payment Link

Generate a payment link that customers can use to complete checkout. Payment links automatically handle HSA/FSA eligibility detection and can be used for both one-time and recurring payments.

<Note>All monetary amounts are integers in cents (e.g., 4995 = \$49.95).</Note>

## Authentication

```bash theme={null}
Authorization: Bearer glm_test_YOUR_API_KEY
```

## Request Body

```json theme={null}
{
  "amount": 4995,
  "currency": "USD",
  "description": "Premium Blood Pressure Monitor",
  "customer": {
    "email": "customer@example.com",
    "first_name": "Jane",
    "last_name": "Doe"
  },
  "products": [
    {
      "merchant_product_id": "BP-MONITOR-001",
      "name": "Blood Pressure Monitor",
      "quantity": 1,
      "price": 4995
    }
  ],
  "payment_type": "one_time",
  "success_url": "https://yoursite.com/success",
  "cancel_url": "https://yoursite.com/cancel",
  "metadata": {
    "order_id": "ORD-12345"
  }
}
```

## Parameters

| Parameter                        | Type      | Required | Description                                        |
| :------------------------------- | :-------- | :------- | :------------------------------------------------- |
| `amount`                         | integer   | Yes      | Total amount in cents                              |
| `currency`                       | string    | Yes      | ISO 4217 currency code (e.g., `"USD"`)             |
| `description`                    | string    | Yes      | Description of the payment                         |
| `customer`                       | object    | No       | Pre-fill customer information                      |
| `customer.email`                 | string    | No       | Customer email                                     |
| `customer.first_name`            | string    | No       | Customer first name                                |
| `customer.last_name`             | string    | No       | Customer last name                                 |
| `products`                       | array     | No       | Product line items                                 |
| `products[].merchant_product_id` | string    | Yes\*    | Your product reference ID                          |
| `products[].name`                | string    | Yes\*    | Product name                                       |
| `products[].quantity`            | integer   | Yes\*    | Quantity                                           |
| `products[].price`               | integer   | Yes\*    | Unit price in cents                                |
| `payment_type`                   | enum      | No       | `one_time` or `subscription` (default: `one_time`) |
| `subscription`                   | object    | No       | Required if `payment_type` is `subscription`       |
| `subscription.interval`          | enum      | Yes\*    | `daily`, `weekly`, `monthly`, `yearly`             |
| `subscription.interval_count`    | integer   | No       | Number of intervals (default: 1)                   |
| `subscription.trial_period_days` | integer   | No       | Free trial days                                    |
| `success_url`                    | string    | Yes      | Redirect URL after successful payment              |
| `cancel_url`                     | string    | No       | Redirect URL if customer cancels                   |
| `metadata`                       | object    | No       | Custom key-value pairs                             |
| `expires_at`                     | timestamp | No       | When link expires (default: 15 days)               |

## Response

```json theme={null}
{
  "id": "plink_abc123xyz",
  "url": "https://checkout.withgale.com/pay/plink_abc123xyz",
  "amount": 4995,
  "currency": "USD",
  "description": "Premium Blood Pressure Monitor",
  "payment_type": "one_time",
  "status": "active",
  "customer": {
    "email": "customer@example.com",
    "first_name": "Jane",
    "last_name": "Doe"
  },
  "products": [
    {
      "merchant_product_id": "BP-MONITOR-001",
      "name": "Blood Pressure Monitor",
      "quantity": 1,
      "price": 4995,
      "hsa_fsa_eligible": true
    }
  ],
  "success_url": "https://yoursite.com/success",
  "cancel_url": "https://yoursite.com/cancel",
  "metadata": {
    "order_id": "ORD-12345"
  },
  "expires_at": "2026-03-12T14:30:00Z",
  "created_at": "2026-02-25T14:30:00Z"
}
```

## Example

```bash theme={null}
curl -X POST https://api.withgale.com/api/v2/payment-links \
  -H "Authorization: Bearer glm_test_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 2995,
    "currency": "USD",
    "description": "Digital Thermometer",
    "products": [
      {
        "merchant_product_id": "THERM-001",
        "name": "Digital Thermometer",
        "quantity": 1,
        "price": 2995
      }
    ],
    "success_url": "https://yoursite.com/success"
  }'
```

## Subscription Intervals

| Interval  | `interval_count` | Billing Frequency          |
| :-------- | :--------------- | :------------------------- |
| `monthly` | 1                | Every month                |
| `monthly` | 3                | Every 3 months (quarterly) |
| `weekly`  | 1                | Every week                 |
| `weekly`  | 2                | Every 2 weeks (bi-weekly)  |
| `yearly`  | 1                | Every year                 |

## Payment Link Status

| Status      | Description                               |
| :---------- | :---------------------------------------- |
| `active`    | Link is active and ready for payment      |
| `expired`   | Link has expired (past `expires_at` time) |
| `paid`      | Payment completed successfully            |
| `cancelled` | Link was cancelled                        |

## Webhooks

When a customer completes payment on a payment link, Gale sends webhook events to your registered endpoints:

* `order.completed` — Payment captured successfully
* `order.failed` — Payment failed or declined

See [Webhooks Reference](/developer-manual/webhooks) for payload examples and setup instructions.

## Errors

| Status Code | Error Code         | Description                              |
| :---------- | :----------------- | :--------------------------------------- |
| 400         | `invalid_request`  | Missing or invalid parameters            |
| 400         | `invalid_amount`   | Amount must be positive integer in cents |
| 401         | `unauthorized`     | Invalid or missing API key               |
| 422         | `validation_error` | Field validation failed                  |

## Related

* [Get Payment Link](/api-reference/endpoint/get-payment-link)
* [List Payment Links](/api-reference/endpoint/list-payment-links)
* [Cancel Payment Link](/api-reference/endpoint/cancel-payment-link)
* [Payment Links Integration Guide](/integration/payment-links)