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

# Payment Links

> Generate shareable payment URLs for off-platform payments via email, SMS, or messaging

# Payment Links Integration

Generate shareable payment URLs for off-platform payments. Perfect for sending invoices via email, SMS payments, social media distribution, or manual billing scenarios.

## When to Use Payment Links

<Check>Perfect for:</Check>

* Sending invoices to customers via email or SMS
* Sharing payment URLs through messaging apps
* Social media bio links or posts
* Manual billing and one-off purchases
* Off-platform payment collection

## How It Works

1. **Create payment link** via dashboard or API
2. **Gale returns** a payment URL
3. **Share the link** with customer via email, SMS, or QR code
4. **Customer clicks** link and completes checkout on Gale's secure page
5. **Gale sends** webhook notification to your system
6. **You fulfill** the order

## Setup Methods

You can create payment links in two ways:

<Tabs>
  <Tab title="Dashboard (No Code)">
    ### Create via Dashboard

    1. **Log in** to your [Gale Dashboard](https://dashboard.withgale.com)
    2. Navigate to **Products** → **Add Product**
    3. Enter product details (name, price, description)
    4. Click **Generate Payment Link**
    5. Copy the link and share it!

    **That's it!** Your payment link is ready to use.

    ### Share Your Link

    **Via Email:**

    ```
    Subject: Complete Your Purchase

    Click here to complete your purchase with your HSA/FSA card:
    https://checkout.withgale.com/pay/pl_abc123xyz
    ```

    **Embed on Website:**

    ```html theme={null}
    <a href="https://checkout.withgale.com/pay/pl_abc123xyz"
       class="btn btn-primary">
      Pay with HSA/FSA
    </a>
    ```

    **QR Code:**
    Generate a QR code from your link using any QR code generator, then print or display it.
  </Tab>

  <Tab title="API (Programmatic)">
    ### Create via API

    Generate payment links programmatically for dynamic scenarios.

    **Endpoint:** `POST /api/v2/payment-links`

    ```bash theme={null}
    curl -X POST https://api.withgale.com/api/v2/payment-links \
      -H "Authorization: Bearer YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "product_id": "prod_abc123",
        "amount": 4999,
        "currency": "USD",
        "metadata": {
          "customer_email": "customer@example.com",
          "order_id": "ORDER-12345"
        }
      }'
    ```

    **Response:**

    ```json theme={null}
    {
      "id": "pl_abc123xyz",
      "url": "https://checkout.withgale.com/pay/pl_abc123xyz",
      "amount": 4999,
      "currency": "USD",
      "expires_at": "2025-11-01T00:00:00Z",
      "active": true
    }
    ```
  </Tab>
</Tabs>

## Subscription Support

Payment links support recurring payments automatically.

### Creating Subscription Links

<Tabs>
  <Tab title="Dashboard">
    1. Create a **Subscription Product** in your dashboard
    2. Set billing frequency (monthly, quarterly, annually)
    3. Generate payment link
    4. Customer agrees to recurring billing at checkout
  </Tab>

  <Tab title="API">
    ```bash theme={null}
    curl -X POST https://api.withgale.com/api/v2/payment-links \
      -H "Authorization: Bearer YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "product_id": "prod_monthly_vitamins",
        "amount": 2999,
        "currency": "USD",
        "subscription": {
          "interval": "monthly",
          "interval_count": 1
        },
        "metadata": {
          "customer_email": "customer@example.com"
        }
      }'
    ```

    **Response includes subscription details:**

    ```json theme={null}
    {
      "id": "pl_sub_xyz789",
      "url": "https://checkout.withgale.com/pay/pl_sub_xyz789",
      "subscription": {
        "interval": "monthly",
        "amount": 2999,
        "trial_days": 0
      }
    }
    ```
  </Tab>
</Tabs>

## Customization Options

### Link Expiration

Set when payment links expire:

```json theme={null}
{
  "expires_at": "2025-12-31T23:59:59Z"
}
```

### Success/Failure URLs

Redirect customers after payment:

```json theme={null}
{
  "success_url": "https://yourdomain.com/success?session_id={CHECKOUT_SESSION_ID}",
  "cancel_url": "https://yourdomain.com/cancel"
}
```

### Metadata

Store custom data with the link:

```json theme={null}
{
  "metadata": {
    "customer_id": "cust_123",
    "campaign": "email_nov_2025",
    "referral_code": "FRIEND20"
  }
}
```

## Handling Payment Confirmation

### Webhooks (Recommended)

Receive real-time notifications when payment is completed. Subscribe to `order.completed` on your webhook endpoint — this fires for every successful payment regardless of how the customer paid.

[Learn more about Webhooks →](/developer-manual/webhooks)

### Polling (Alternative)

If your server missed a webhook or you need to check status on demand, poll the checkout status endpoint using the checkout ID (`cs_xxx`) returned when the cart was created:

```bash theme={null}
GET /api/v2/checkout/{checkout_id}
```

[See the endpoint reference →](/api-reference/endpoint/get-checkout)

## Best Practices

<CardGroup cols={2}>
  <Card title="Use Expiration Dates" icon="clock">
    Set reasonable expiration dates (7-30 days) to keep links fresh
  </Card>

  <Card title="Include Metadata" icon="tag">
    Store order IDs, customer info for easy reconciliation
  </Card>

  <Card title="Test Mode First" icon="flask">
    Use test API keys to verify flow before going live
  </Card>

  <Card title="Monitor Webhooks" icon="bell">
    Set up webhook endpoints for reliable order fulfillment
  </Card>
</CardGroup>

## Common Use Cases

* **Membership Sign-Up**: Generate link when user selects tier, email to customer
* **Email Campaigns**: Include payment link in promotional emails
* **Social Media**: Add to Instagram bio, Facebook posts, or Twitter links
* **Manual Billing**: Send invoices to customers via email or SMS

## Testing

### Test Mode Links

Use test API keys to create test links:

```bash theme={null}
curl -X POST https://api.withgale.com/api/v2/payment-links \
  -H "Authorization: Bearer glm_test_YOUR_TEST_KEY" \
  ...
```

### Test Cards

Use these test HSA cards on checkout:

| Card Number        | Scenario           |
| ------------------ | ------------------ |
| `4111111111111111` | Successful payment |
| `4000000000000002` | Card declined      |
| `4000000000000069` | Expired card       |

[See all test cards →](/resources/test-cards)

## Going Live

<Steps>
  <Step title="Test Thoroughly">
    Create test payment links and complete test checkouts
  </Step>

  <Step title="Set Up Webhooks">
    Configure webhook endpoints for payment notifications
  </Step>

  <Step title="Switch to Live Keys">
    Replace test API keys with live keys
  </Step>

  <Step title="Monitor">
    Watch for successful payments in your dashboard
  </Step>
</Steps>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Link shows as expired">
    **Solution:** Check the `expires_at` date. Create a new link or update the expiration via API.
  </Accordion>

  <Accordion title="Customer can't complete payment">
    **Possible causes:**

    * Product not HSA/FSA eligible → Check eligibility in dashboard
    * Card declined → Customer should contact their HSA/FSA provider
    * Link expired → Generate new link
  </Accordion>

  <Accordion title="Not receiving webhooks">
    **Solution:**

    1. Verify webhook URL is publicly accessible
    2. Check webhook delivery logs in dashboard under **Settings → Webhooks**
    3. Ensure HTTPS endpoint
    4. Confirm the `Authorization: Bearer` token in your handler matches the secret shown when you created the endpoint

    [Webhook setup guide →](/developer-manual/webhooks)
  </Accordion>

  <Accordion title="Want to update product price">
    **Solution:** Payment links are immutable once created. Generate a new link with updated price.
  </Accordion>
</AccordionGroup>

## API Reference

For complete API documentation:

* [Create Payment Link](/api-reference/endpoint/create-payment-link)
* [Get Payment Link](/api-reference/endpoint/get-payment-link)
* [List Payment Links](/api-reference/endpoint/list-payment-links)

## Next Steps

<CardGroup cols={2}>
  <Card title="Set Up Webhooks" icon="bell" href="/developer-manual/webhooks">
    Configure real-time payment notifications
  </Card>

  <Card title="Test Cards" icon="credit-card" href="/resources/test-cards">
    Test your integration with test HSA cards
  </Card>

  <Card title="Embedded Checkout" icon="window" href="/integration/embedded-checkout">
    Upgrade to embedded checkout for branded experience
  </Card>

  <Card title="API Reference" icon="book" href="/api-reference/introduction">
    Explore the full API
  </Card>
</CardGroup>

## Support

Need help with payment links?

* 📧 Email: [support@withgale.com](mailto:support@withgale.com)
* 💬 [Contact Support](https://www.withgale.com/contact/support)