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

# Integration Flow

> Understand the end-to-end flow of integrating with the Gale API platform.

This page outlines the complete sequence of steps required to successfully integrate with Gale's API platform.

## 1. Product Sync

Before initiating any checkout session, sync your product catalog with Gale. Each product includes metadata such as name, UPC/GTIN, and a unique product ID from your system.

Endpoint:

```
POST /api/v2/products
```

This step ensures Gale has full context of the items you intend to sell through the hosted checkout. See the [Product API Reference](/api-reference/endpoint/create-product-v2) for full details.

## 2. Eligibility Classification

Once products are synced, Gale automatically checks HSA/FSA eligibility against the SIGIS database. Each product response includes:

* `hsa_fsa_eligible` — boolean indicating whether the product qualifies for HSA/FSA
* `message` — a customer-facing explanation you can display on your storefront (e.g., "HSA/FSA accepted", "Requires Letter of Medical Necessity")

You can:

* Check the `hsa_fsa_eligible` field on any product response
* Query eligibility using the [Check Eligibility](/api-reference/endpoint/check-eligibility) endpoint
* Subscribe to webhook events (`product.updated`) for real-time eligibility updates

## 3. Hosted Checkout Session

With eligible products in place, initiate a hosted checkout session using the Gale API.

Endpoint:

```
POST /api/v2/checkout
```

You must include customer details, line items, shipping, tax, and a `reference_id` (your order or cart ID for correlation). A successful response returns a `checkout_id` and `checkout_url` which you redirect your customer to.

Gale automatically determines the checkout type based on product eligibility:

* **Eligible** - All items are HSA/FSA eligible, entire amount charged to HSA/FSA card
* **Split** - Mix of eligible and non-eligible items, Gale handles splitting payment across HSA/FSA and regular payment methods
* **Regular** - No items are eligible, standard payment processing

See [Checkout API Reference](/api-reference/endpoint/create-checkout-v2) for full request/response details.

## 4. Payment Processing

The customer completes payment on Gale's hosted checkout page. Once paid, an **order** is created.

### Order Lifecycle

Orders track both fulfillment and payment separately:

**Order Status** (your fulfillment state):

* `pending` - Order created, awaiting payment
* `processing` - Payment in progress
* `completed` - Payment successful, ready to fulfill
* `failed` - Payment declined
* `cancelled` - Order cancelled

**Payment Status** (money movement):

* `pending` - Payment not attempted
* `authorized` - Funds reserved (not yet captured)
* `captured` - Funds captured successfully
* `refunded` - Funds returned to customer

This separation gives you flexibility. For example, an order can be `completed` while payment is still `authorized` (not yet captured).

**Most merchants only need to check:** Order `status === 'completed'` means the order is paid and ready to ship.

Check order status anytime:

```
GET /api/v2/orders/{order_id}
```

### Three Key IDs

Keep these distinct:

| ID             | What it is                                  | When you get it                           |
| -------------- | ------------------------------------------- | ----------------------------------------- |
| `checkout_id`  | The checkout session you created            | Returned when you create a checkout       |
| `order_id`     | The payment record after successful payment | Returned in webhooks and order queries    |
| `reference_id` | Your own order/cart ID for correlation      | You provide this when creating a checkout |

## 5. Webhook Notifications

Gale sends webhooks when important events occur. All payment flows (checkout sessions, payment links) create orders, so you'll receive order webhooks.

### Common Webhooks

**For Checkout Sessions:**

* `order.created` - Order created after successful payment
* `order.failed` - Payment failed
* `order.refunded` - Order was refunded

**For Payment Links:**

* `payment_link.paid` - Customer paid the link
* `order.created` - Order created from the payment (fires after `payment_link.paid`)
* `payment_link.expired` - Link expired without payment

**For Products:**

* `product.updated` - Eligibility status changed (e.g., SIGIS update)

### Setup

1. Register your webhook URL in **Settings** > **Webhooks** in the Gale Dashboard
2. Validate signatures using `X-Gale-Signature` header
3. Respond with HTTP 200 within 5 seconds
4. Gale retries failed deliveries with exponential backoff

See [Webhooks Reference](/developer-manual/webhooks) for all event types and examples.

## 6. Refunds

You can issue full refunds via the API:

```
POST /api/v2/refunds
```

For split checkout sessions (where payment was split across HSA/FSA and regular payment methods), partial refunds are managed through the [Gale Dashboard](https://dashboard.withgale.com).

See [Refund API Reference](/api-reference/endpoint/create-refund) for details.

## Summary

| Step               | Description                               |
| ------------------ | ----------------------------------------- |
| Product Sync       | Send your products to Gale                |
| Eligibility        | Check which items are HSA/FSA eligible    |
| Create Checkout    | Launch a hosted checkout session          |
| Process Payment    | Customer completes payment on Gale's page |
| Listen to Webhooks | Receive real-time updates                 |
| Handle Refunds     | Process returns via API or Dashboard      |

Refer to the API Reference section for implementation details of each step.