Enable HSA/FSA Payments

If you’re already using 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 a variety of health-related goods directly at checkout. Together, these payment options represent a significant market, with HSA balances exceeding $116 billion across 36 million accounts and FSAs accounting for $3.6 billion in yearly contributions (current as of 2024).

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.

HSA/FSA item eligibility is governed by the SIGIS Eligible Product List (EPL), an industry-standard resource that identifies which items qualify for HSA/FSA spending. This ensures that customers can confidently purchase approved items like over-the-counter (OTC) medications and health-related supplies without manual intervention. By leveraging the SIGIS EPL, your application handles eligibility in carousels, search results and at checkout, enhancing the 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 currently only available to merchants using our existing EBT services.
• Your system can refresh HSA/FSA item eligibility according to the SIGIS EPL, which is updated monthly.

SIGIS Certification FAQs

In order to process HSA/FSA payments in production, you must:

• Be a SIGIS member
• Complete your IIAS Certification
• Have the required merchant codes from the Issuing Networks

Forage provides operational support throughout this process.

For questions about SIGIS certification, downloading and using the SIGIS EPL, and more, see SIGIS Eligible Product List Overview > Related FAQs.

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 Quickstart Guide, iOS Quickstart Guide, or JavaScript Quickstart guide. If not, please reach out to our Sales team before proceeding, as this guide builds on those foundational steps.

You will need to integrate the ForageHealthCardEditText SDK element in to your application for HSA/FSA. This is largely similar to the ForagePANEditText SDK element that is used for SNAP Payments except for some 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), which is the first six to nine digits of the card number, and returns a 400 error if a user tries to add a non HSA/FSA card.

Ensure that 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 funding_type field set to hsa_fsa.

The amount that you set on the payment is the amount that you intend to authorize. See next steps for capturing this amount.

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 recommended. Providing this information can reduce rates 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 failed.

• On success, the response includes an updated Forage Payment object representing the authorized transaction.
• On failure, you will receive an error response following the format outlined here.

Once authorized, the amount field in the Payment object reflects the authorized amount. After the transaction is captured, this field updates to show 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 status capture_submitted. Capture requests are processed in batches, and the Payment object will move to status succeeded after the card network finalizes the transaction. Subscribe to our webhooks to be notified of Payment status updates.

After capture, the amount field updates to the captured amount. The originally authorized amount moves to authorization_amount, which is only used for bookkeeping and debugging.

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 immediately 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 PaymentRefund object includes a funding_type field set to hsa_fsa, similar to the authorization endpoint.

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 begin processing HSA/FSA payments, these transactions appear in your transaction reports.

🚧

Important

HSA/FSA transaction reporting is available on API version 2024-08-30. 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 referred to as a chargeback, occurs when a cardholder challenges a transaction on their statement with the issuing bank. Disputes are common with credit cards; HSA/FSA cards are primarily debit cards, which tend to have a lower dispute rate.

The dispute process for debit cards is governed by the Electronic Fund Transfer Act (EFTA) and is generally more stringent than that for credit cards. Cardholders are required to report disputes within shorter timeframes compared to credit card transactions, resulting in 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: Forage sends a webhook containing relevant information, such as payment details and the dispute state, when a dispute is initiated.
• Challenging the Dispute: You can challenge the dispute by submitting evidence to Forage's ops team. Effective 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. This guide does not include the interface details. 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 makes the final determination on whether the dispute is upheld. Forage will notify the retailer regarding the result of the dispute.

Next Steps

Here are some other resources to consider:

• Android Quickstart Guide - Essential for setting up the Forage SDK and foundational payment processing.
• Payment API Overview - Comprehensive documentation for creating, authorizing, and capturing payments.