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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.