Enable HSA/FSA Payments

If you already use Forage for EBT processing, great news—HSA/FSA payments are an easy addition! This guide shows you how to unlock HSA/FSA functionality with minimal effort. With your existing setup, you’re already most of the way there.

HSA/FSA payment processing

Health Savings Accounts (HSAs) and Flexible Spending Accounts (FSAs) provide tax-advantaged payment methods that customers can use to cover eligible expenses. Customers with HSA and/or FSA cards can purchase various health-related goods directly at checkout. These payment options represent a significant market, with HSA balances exceeding $137 billion across nearly 38 million accounts as of mid-2024, reflecting an 18% increase in assets from the previous year. FSAs remain widely used, with the IRS raising the annual contribution limit to $3,200 for 2024, indicating potential growth in total contributions.

Luckily, Forage makes it simple to accept these cards! Since you’ve already set up SNAP and/or EBT Cash payments, this guide walks you through enabling HSA/FSA payment processing using your existing integration. This seamless addition builds on what you’ve already implemented, expanding your payment capabilities effortlessly while tapping into the growing HSA/FSA market.

The eligibility of HSA/FSA items is guided by IRS regulations, particularly 26 U.S.C. § 213(d), which details what counts as qualified medical expenses. To qualify as "medical care," expenses must meet certain criteria, including amounts paid for:

• Diagnosis, cure, mitigation, treatment, or prevention of disease
• Affecting any structure or function of the body

Forage's Catalog Assistant identifies HSA/FSA-eligible items in your catalog, allowing customers to buy approved products like OTC medications confidently without manual checks. It automates eligibility in carousels, search results, and at checkout, improving customer experience.

What this guide covers

After you’ve finished this guide, you’ll have accomplished the following:

• Tokenize an HSA/FSA payment method
• Authorize and Capture an HSA/FSA payment
• Refund an HSA/FSA payment
• Access HSA/FSA transaction reports
• Handle disputes

Requirements

Before enabling HSA/FSA payment processing with Forage, confirm the following:

• You’re already processing EBT transactions with Forage. HSA/FSA payment processing is only available to merchants using our existing EBT services.

Compliance and Certification

To process HSA/FSA payments in production, you must:

• Tag your inventory’s HSA/FSA eligibility
• Provide itemized receipt data to Forage to ensure continued compliance
• Demo your checkout flow to the Forage compliance team

Forage provides operational support throughout this process.

Tokenize an HSA/FSA payment method

📘 Before you begin

We assume you’ve already set up Forage payment processing capability in your app using our Android, iOS, or JavaScript Quickstart guides. If not, please contact our Sales team before proceeding, as this guide builds on those foundational steps.

You will need to integrate the ForageHealthCardEditText SDK element into your application for HSA/FSA. This is similar to the ForagePANEditText SDK element used for SNAP Payments, with a few extra fields. The ForageHealthCardEditText element allows for seamless input and validation of account numbers—without requiring additional customization.

The key difference between HSA/FSA and EBT cards is that HSA/FSA requires a security code (often called CVV), zip code, cardholder name, expiration month, and expiration year.

The ForageHealthCardEditText element detects the card type based on the Bank Identification Number (BIN), the first six to nine digits of the card number. If a user tries to add a non-HSA/FSA card, it returns a 400 error.

Ensure you use the ForageHealthCardEditText element when adding HSA/FSA payment methods.

The Forage SDK validates and properly tokenizes the following fields:

Authorize and Capture an HSA/FSA payment

The HSA/FSA payment flow follows a standard authorize-and-capture pattern.

In brief, here’s how to authorize and capture an HSA/FSA payment:

1. Create payment object (POST /api/payments/)
2. Initiate authorization (POST /api/payments/<payment_ref>/authorize)
3. Capture the authorization payment funds. (POST payments/<payment_ref>/capture/

The next sections break out each step of this process in detail.

Step 1. Create a payment

First, Create a payment with the payment_method field set to the HSA/FSA payment method created via the ForageHealthCardEditText SDK element and the funding_type field set to credit_payfac.

The amount you set on the payment is the amount you intend to authorize. For instructions on capturing this amount, see the next steps.

The following fields are optional for HSA/FSA payments, but are required for EBT payments. You may include these fields in your HSA/FSA payments:

The delivery_address field is optional for HSA/FSA payments, but you are advised to provide it. Supplying this information can lower the risk of fraud.

The delivery_address field may have the following properties:

Step 2. Initiate the authorization

After creating the Forage Payment object, call the /api/payments/<payment_ref>/authorize endpoint to initiate an authorization for the specified amount. The API will synchronously return a response indicating whether the authorization was successful or not.

• When successful, the response includes an updated Forage Payment object that represents the authorized transaction.
• If it fails, you will receive an error response in the format outlined here.

Once authorized, the amount field in the Payment object displays the authorized amount. After the transaction, this field updates to indicate the final captured amount.

Step 3. Capture the authorization payment funds

To secure the authorized funds, you must explicitly capture them as part of the HSA/FSA payment flow.

🚧

Important

All authorizations must be captured within 7 days, or the authorization will expire and release the funds.

To capture a payment, send a POST request to: /api/payments/{payment_ref}/capture_payment/

Include the payment_ref from Step 1 (Create a Payment) in the request.

🚧

Only use capture_amount for HSA/FSA payments. The capture_amount must be less than or equal to the originally authorized amount.

Passing capture_amount for non-HSA/FSA transactions may result in unexpected behavior.

A 200 response confirms that the Payment has moved to the capture_submitted status. Capture requests are processed in batches, and the Payment object will move to the succeeded status after the card network finalizes the transaction. Subscribe to our webhooks to receive payment status updates.

After capture, the amount field updates to reflect the captured amount. The initially authorized amount transfers to authorization_amount, which is solely used for bookkeeping and debugging purposes.

Refund a HSA/FSA payment

🚧

Important

Merchants must process HSA/FSA refunds by returning them to the original payment method. This is essential to minimize fraud and maintain compliance with HSA/FSA tax regulations.

Once a refund request is initiated, Forage begins processing it, which has immediate financial implications. Ensure your system handles refund requests carefully and submits them only when necessary.

Refunds for HSA/FSA transactions are processed through the existing refund endpoints.

The behavior of the Refund API varies based on the authorized and captured states of the original transaction:

Access Reports

HSA/FSA transactions are accessible through the same Reporting APIs used for your company’s EBT/SNAP transactions. Specifically, calling the Retrieve a Transaction Report endpoint returns both EBT and HSA/FSA transactions. Once you start processing HSA/FSA payments, these transactions will appear in your transaction reports.

🚧

Important

HSA/FSA transaction reporting is available on API version 2024-08-30 or newer. If you are using an earlier API version, you may have to upgrade to receive HSA/FSA transaction data.

HSA/FSA transaction objects contain the same fields as EBT transactions, but include additional valid transaction types:

• HSA_FSA_Purchase
• HSA_FSA_Refund
• HSA_FSA_Chargeback

This ensures consistent reporting while accommodating the extended functionality for HSA/FSA payments.

Handle Disputes

A dispute, also known as a chargeback, arises when a cardholder contests a transaction on their statement with the issuing bank. Disputes are common with credit cards; however, HSA/FSA cards are primarily debit cards, which typically have a lower dispute rate.

The dispute process for debit cards is governed by the Electronic Fund Transfer Act (EFTA) and is typically more stringent than that for credit cards. Cardholders must report disputes within shorter timeframes than credit card transactions, leading to a more streamlined dispute resolution process.

Here’s a diagram of the process, with details following:

Dispute Initiation

When a customer initiates a dispute, the following actions occur:

• Reversal of the Original Payment: The original payment is reversed, and a new transaction appears with the type HSA_FSA_Chargeback in future reports.
• Impact on Payouts: When a dispute is initiated, the disputed amount is immediately deducted from your next payout. If the total dispute amount exceeds your next payout, future payouts will be paused until the full amount is recovered.
• Webhook Notification: When a dispute is initiated, Forage sends a webhook containing relevant information, such as payment details and the dispute state.
• Challenging the Dispute: You can challenge the dispute by submitting evidence to Forage's ops team. Compelling evidence to support your case might include:
  • Email threads or screenshots of conversations with the cardholder.
  • Proof of consistent use of a service or software over time.
  • Product photos or e-signature contracts.
  • Returns/refund policies, proof of shipping, or other relevant materials.
• Accepting the Dispute: If you lack sufficient evidence or deem the dispute not worth contesting, you can concede liability and accept the dispute.
• Winning the Dispute: If the dispute is resolved in your favor, the disputed funds are refunded to your account.

📘

Note

The dispute webhook is still under development, and the interface details are not included in this guide. Please contact your integration engineer for the latest updates on these features.

Dispute Handling

The retailer has the following options when handling a dispute:

• Accept the Dispute: The retailer can concede liability and accept the dispute without providing further evidence.
• Challenge the Dispute: To contest the dispute, the retailer may submit evidence. The following rules apply for submitting evidence:
  • A maximum of 8 files can be submitted.
  • Files must be in JPG, PNG, or PDF formats and cannot exceed 10MB each.

Once evidence is submitted, the issuing bank reviews the documentation and decides whether to uphold the dispute. Forage will inform the retailer of the result dispute.

Next Steps

Here are some other resources to consider:

• Do you need to set up the Forage SDK and start processing payments? The Android Quickstart Guide provides step-by-step instructions.
• The Payment API Overview contains everything necessary to create, authorize, and capture transactions seamlessly when working with payments.