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, sync your product catalog with Gale. Each product includes metadata such as name, UPC/GTIN, and a unique product ID from your system. Endpoint:
This step ensures Gale has full context of the items you intend to sell through the hosted checkout. See the Product API Reference 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 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:
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 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:

​
Three Key IDs

Keep these distinct:

​
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

You can issue full refunds via the API:
For split checkout sessions (where payment was split across HSA/FSA and regular payment methods), partial refunds are managed through the Gale Dashboard. See Refund API Reference for details.

​
Summary

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