Stripe Billing Subscriptions

Use this when the subscription lives in your Stripe account: Stripe creates an invoice for each cycle, and tools that follow Stripe Billing act on invoice.paid. Gale charges the shopper’s HSA/FSA card for each invoice and tells Stripe, so Stripe marks the invoice paid and keeps the subscription active. Your system starts every charge. Gale keeps no schedule.

This flow is switched on per merchant account. Ask your Gale contact to enable it for your test account before you start.

Who does what

	Stripe	Gale	You
Subscription, plan, billing dates	Owns them		Create and cancel them in Stripe
Card details	Never sees them	Collects them on its hosted page and stores the card
Charging the card		Charges it, first payment and renewals	Start each charge by API
Invoice status	Marks it paid when Gale attaches the payment	Attaches the payment
Access to your product	Sends `invoice.paid`	Sends `order.completed`	Grant access from either

Before you start

Create a custom payment method type in Stripe for Pay with FSA/HSA, as in Step 1 of the Stripe Payment Element page. You need its cpmt_... id.
Save a restricted key on Gale on Stripe. Set Payment Records to Write and Invoices to Write. Gale needs nothing on charges, balance or payouts.
Saved payment methods are enabled for your account.
The product you sell is registered in your Gale catalog. Gale reviews each product for HSA/FSA eligibility. A digital product needs no UPC.

How it works

You create the Stripe customer and the subscription, with your custom payment method as its default.
For the first invoice, you create a Gale checkout that stores the card and names the Stripe customer and invoice.
The shopper pays on Gale’s page. Gale writes a payment record to your Stripe account and attaches it to the invoice.
Stripe marks the invoice paid and the subscription active, and sends invoice.paid.
For each renewal, Stripe sends you invoice.payment_attempt_required. You charge the stored card through Gale and name the new invoice.

Step 1: Create the subscription in Stripe

Create a payment method of your custom type, attach it to the customer, and create the subscription with payment_behavior: "default_incomplete".

const paymentMethod = await stripe.paymentMethods.create({
  type: 'custom',
  custom: { type: 'cpmt_...' },   // your Pay with FSA/HSA type id
});
await stripe.paymentMethods.attach(paymentMethod.id, { customer: customer.id });

const subscription = await stripe.subscriptions.create({
  customer: customer.id,
  items: [{ price: 'price_...' }],
  payment_behavior: 'default_incomplete',
  default_payment_method: paymentMethod.id,
});
// subscription.latest_invoice is the first invoice, status "open"

Stripe expires an incomplete subscription 23 hours after it is created. Send the shopper to the Gale checkout right away.

Step 2: Collect the first invoice

Create a Gale checkout for the invoice amount. Three keys in metadata tie it to Stripe.

{
  "reference_id": "in_1Abc...",
  "customer": { "email": "jane@example.com", "first_name": "Jane", "last_name": "Doe" },
  "line_items": [
    { "product_id": "MEMBERSHIP", "name": "Monthly membership", "price": 2500, "quantity": 1, "currency": "USD" }
  ],
  "shipping_info": {
    "address_line_1": "1 Main St", "city": "Austin", "state": "TX", "postal_code": "78701", "country": "US"
  },
  "success_url": "https://yoursite.com/welcome",
  "failure_url": "https://yoursite.com/pricing",
  "setup_future_usage": "off_session",
  "metadata": {
    "payment_source": "stripe_elements_cpm",
    "stripe_customer_id": "cus_...",
    "stripe_invoice_id": "in_1Abc..."
  }
}

Key	Value
`payment_source`	`stripe_elements_cpm`. Gale writes the payment to your Stripe account
`stripe_customer_id`	The customer on the invoice
`stripe_invoice_id`	The open invoice this payment settles. Needs `stripe_customer_id`

The checkout total has to equal the invoice total. Stripe refuses a payment of a different amount. customer.email, customer.first_name and customer.last_name are required. customer.phone is optional. shipping_info is required even for a digital product, so send the customer’s billing address there. Card details are entered on Gale’s page. When the shopper pays, you receive payment_method.id on the order.completed webhook. Store it against the Stripe customer.

Step 3: Collect each renewal

Listen for invoice.payment_attempt_required on your Stripe webhook. Charge the stored card for that invoice.

curl -X POST https://api.withgale.com/api/v2/payment-methods/pm_.../charges \
  -H "Authorization: Bearer glm_test_YOUR_API_KEY" \
  -H "Idempotency-Key: in_1Def...-attempt-1" \
  -H "Content-Type: application/json" \
  -d '{
    "reference_id": "in_1Def...",
    "line_items": [
      { "product_id": "MEMBERSHIP", "name": "Monthly membership", "price": 2500, "quantity": 1, "currency": "USD" }
    ],
    "metadata": {
      "payment_source": "stripe_elements_cpm",
      "stripe_customer_id": "cus_...",
      "stripe_invoice_id": "in_1Def..."
    }
  }'

Gale charges the card, writes the payment record, and attaches it to the invoice. Stripe sends invoice.paid once the payment is captured.

What you see where

Event	Where it arrives
A cycle is due	Stripe: `invoice.payment_attempt_required`
The payment succeeded	Gale: `order.completed`. Stripe: `invoice.paid`
The card was declined	Gale: `422` on the charge, with a `checkout_url` for the shopper. The Stripe invoice stays open
A refund	Gale: `refund.created`, `refund.succeeded`, `refund.failed`

Declines

A declined renewal returns 422 with PAYMENT_METHOD_010 and a checkout_url. Send that link to the shopper so they can pay with another card. Gale does not retry a declined charge. If you use Stripe’s retry schedule, each retry sends invoice.payment_attempt_required again, and you call the charge again with a new Idempotency-Key.

Refunds and disputes

Refund the Gale order with POST /api/v2/refunds. Gale reports the refund to the payment record in Stripe. Stripe does not send charge.refunded, and Gale does not create a credit note. Create one in Stripe if your books need it. Stripe does not hold disputes for payments processed outside Stripe, so a dispute on one of these payments does not appear in your Stripe account. Stripe lists this in its limitations.

Cancelling

Cancel the subscription in Stripe, the way you do today. There is nothing to cancel on Gale, because Gale only charges when you ask. If the customer wants their card removed, call DELETE /api/v2/payment-methods/{id}.

Webhooks

Gale signs every webhook with X-Gale-Signature and retries a failed delivery. Add your endpoint in the Gale dashboard under Developer Tools > Webhooks. See Webhooks for the signature check and every event.

Testing

Use a glm_test_ key and a restricted key from your Stripe sandbox. Put the Stripe customer on a test clock and advance it one cycle to make Stripe send invoice.payment_attempt_required. Pay with Gale’s test cards.

Limits

One invoice per charge, and the amounts have to match.
A renewal cannot mix eligible and non-eligible items, and cannot include an item that needs a Letter of Medical Necessity.
To change the shopper’s card, send them a new checkout with setup_future_usage and remove the old payment method.

Get Started

Integration

Promotional Resources

Custom Payment Methods

Stripe Billing Subscriptions

Who does what

Before you start

How it works

Step 1: Create the subscription in Stripe

Step 2: Collect the first invoice

Step 3: Collect each renewal

What you see where

Declines

Refunds and disputes

Cancelling

Webhooks

Testing

Limits

​Who does what

​Before you start

​How it works

​Step 1: Create the subscription in Stripe

​Step 2: Collect the first invoice

​Step 3: Collect each renewal

​What you see where

​Declines

​Refunds and disputes

​Cancelling

​Webhooks

​Testing

​Limits

​Related

Who does what

Before you start

How it works

Step 1: Create the subscription in Stripe

Step 2: Collect the first invoice

Step 3: Collect each renewal

What you see where

Declines

Refunds and disputes

Cancelling

Webhooks

Testing

Limits

Related