Skip to main content
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, you must sync your product catalog with Gale. Each product includes metadata such as name, UPC, GTIN, category, and a unique external_id. Endpoint: 
POST /v1/products
This step ensures Gale has full context of the items you intend to sell through the hosted checkout.

​
2. Eligibility Classification

Once products are synced, Gale automatically checks HSA/FSA eligibility against the SIGIS database. You can:
  • Query individual or batch product eligibility using the API
  • Subscribe to webhook events (product.updated) for real-time updates
Products are classified as:
  • Auto-substantiation (auto_substantiation) - Automatically eligible via SIGIS verification, no additional documentation needed
  • Dual-purpose (dual_purpose) - Requires Letter of Medical Necessity (LMN) from doctor
  • Vision (vision) - Vision care products
  • Prescription (rx) - Prescription items
  • Not eligible - Products that don’t qualify for HSA/FSA

​
3. Hosted Checkout Session

With eligible products in place, initiate a hosted checkout session using the Gale API. Endpoint: 
POST /v1/checkout
You must include customer details, line items, tax, shipping, and total amounts. A successful response returns a checkout_url which you should redirect your customer to.

​
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 /v2/orders/{order_id}

​
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 for all event types and examples.

​
6. Refunds and Cancellations

You can issue full or partial refunds via: 
POST /v1/checkout/{checkout_id}/refund
Or cancel unpaid sessions via: 
POST /v1/checkout/{checkout_id}/cancel
Ensure that your backend reflects these changes and listens to webhook confirmations when possible.

​
Summary

StepDescription
Product SyncSend your products to Gale
EligibilityCheck which items are HSA/FSA eligible
Create CheckoutLaunch a hosted checkout session
Process PaymentCustomer completes payment on Gale’s page
Listen to WebhooksReceive real-time updates
Handle RefundsProcess returns or cancellations
Refer to the API Reference section for implementation details of each step.