Terminal-2 icon

FSA/HSA healthcare payments with IIAS

Accept Flexible Spending Account (FSA) and Health Savings Account (HSA) payments in the US.

SIG-IS registration

This page covers the IIAS program. If your business uses Direct Medical Services or the 90% Rule, you do not need this integration. See SIG-IS registration and certification.

In the US, you can use Adyen payment terminals to accept FSA/HSA payments for eligible healthcare products if your business is SIG-IS-certified. FSA/HSA payments are supported for US-issued Visa and Mastercard cards. Your POS app uses an Inventory Information Approval System (IIAS) to identify eligible healthcare products. This page explains how to identify FSA/HSA cards and make FSA/HSA payments with a Terminal API integration.

Requirements

Before you begin, take into account the following requirements, limitations, and preparations.

Requirement Description
Integration type A Terminal API integration with payment terminals using terminal software version 1.136.3 or later.
Limitations FSA/HSA payments do not support offline payments, including Store and Forward and offline EMV. See Limitations.
Setup steps Before you begin:
  • Register or certify your business with SIG-IS. The program that applies depends on your business type. See SIG-IS registration and certification.
  • Contact your Adyen account manager to enable FSA/HSA payments on your account.
  • Ensure your integration supports partial authorizations, to be able to process FSA/HSA payments.

Limitations and product eligibility

Your POS app must:

  • Identify eligible items by checking your inventory against the SIG-IS Eligible Product List.
  • Calculate the eligible and ineligible totals.
  • Make separate payments for eligible and ineligible items.

Adyen does not determine product eligibility or calculate these amounts.

FSA/HSA payments do not support offline payments. This applies to both Store and Forward and offline EMV. When the terminal cannot reach Adyen's backend, it blocks the transaction instead of saving it for later. For how to handle this, see the Failure result under Make an FSA/HSA payment.

Payments that do not include healthcare fields keep the standard offline payment behavior.

To refund an FSA/HSA payment, use the standard refund flows: a referenced refund or an unreferenced refund. Refunds have no FSA/HSA-specific requirements.

How it works

The FSA/HSA payment flow is as follows:

  1. The shopper presents their card to the payment terminal.
  2. You make a card acquisition request to identify whether the shopper used an FSA/HSA card.

    FSA/HSA is not a separate payment brand. Eligible cards use Visa or Mastercard. A card can be co-badged with a US Debit network, such as STAR, but Adyen processes FSA/HSA payments only over the Visa or Mastercard network.

    If any of the card's brands is healthcare-eligible, the response returns healthcareIndicator true. Your POS app does not need to select a brand for FSA/HSA processing.

  3. The card acquisition response determines how you continue:
    • If the response identifies an FSA/HSA card, your POS app identifies the eligible items and calculates the eligible and ineligible totals.
    • Otherwise, your store staff asks the shopper how to continue. The shopper can continue with a regular payment using the acquired card, or use another card. If the shopper wants to use another card, you cancel the card acquisition.
  4. For an FSA/HSA card, you make an FSA/HSA payment for eligible healthcare items only.
  5. From the payment response you learn the amount approved by the issuer:
    • If the issuer approves the full eligible amount, the FSA/HSA payment is complete.
    • If the shopper's FSA/HSA account does not have enough funds, it is possible that the issuer still approves part of the eligible amount.
  6. If the issuer approved only part of the eligible amount, make a follow-up payment to let the shopper pay the remaining amount with another card.
  7. If the purchase includes ineligible items, make a separate payment for them using another payment method.

Identify FSA/HSA cards

To identify an FSA/HSA card:

  1. Make a card acquisition request with:

    • The standard SaleToPOIRequest.MessageHeader object, with MessageClass set to Service and MessageCategory set to CardAcquisition.

      Parameter Required Description
      ProtocolVersion -white_check_mark- 3.0
      MessageClass -white_check_mark- Service
      MessageCategory -white_check_mark- CardAcquisition
      MessageType -white_check_mark- Request
      ServiceID -white_check_mark- Your unique ID for this request, consisting of 1-10 alphanumeric characters. Must be unique within the last 48 hours for the terminal (POIID) being used.
      SaleID -white_check_mark- Your unique ID for the POS system component to send this request from.
      POIID -white_check_mark- The unique ID of the terminal to send this request to. Format: [device model]-[serial number].
    • The CardAcquisitionRequest object with:

      Parameter Required Description
      SaleData.SaleTransactionID -white_check_mark- An object with:
      • TransactionID: your reference to identify a payment. We recommend a unique value for each payment.
      • TimeStamp: date and time of the request in UTC format.
      CardAcquisitionTransaction -white_check_mark- A required object that can be empty or contain:
      • TotalAmount (optional): the transaction amount. When you do not know the amount yet, you can omit this parameter or specify an initial amount. If you specify an initial amount, provide the final amount later in the payment request.
      • PaymentType (optional): if you intend to continue with a payment, either omit this parameter or specify Normal.
  2. When you receive the CardAcquisitionResponse, save the TimeStamp and TransactionID from POIData.POITransactionID. You will need these details if you continue with a payment request using the acquired card. The Response.AdditionalResponse field contains either form-encoded key-value pairs or a Base64-encoded JSON object. If it is Base64-encoded, decode it to get the JSON object.

  3. To find out whether the card is an FSA/HSA card, check whether AdditionalResponse contains the healthcareIndicator key to decide on the next step:

    • If Result is Success and healthcareIndicator is true, the card is an FSA/HSA card. Your POS app identifies the eligible items and calculates the eligible amount. Then make an FSA/HSA payment.
    • If Result is Success and healthcareIndicator is not present, the response does not identify the card as an FSA/HSA card. The response never returns healthcareIndicator false. A missing key means that the card is not an FSA/HSA card, or that the terminal cannot reach the backend. You decide whether to continue with a regular payment:
      • If the shopper wants to use the acquired card, finish the card acquisition in the regular way with a payment request that includes PaymentData.CardAcquisitionReference but does not include healthcare fields.
      • If the shopper wants to use another card, cancel the card acquisition. Then make a new card acquisition request to identify the new card, and continue based on the response.

Make an FSA/HSA payment

To make an FSA/HSA payment for eligible items:

  1. Configure your POS app to validate healthcare amounts before you send a payment request. See Healthcare amount rules.

  2. Make a Terminal API payment request, specifying:

    • The standard SaleToPOIRequest.MessageHeader object, with MessageClass set to Service and MessageCategory set to Payment.

      Parameter Required Description
      ProtocolVersion -white_check_mark- 3.0
      MessageClass -white_check_mark- Service
      MessageCategory -white_check_mark- Payment
      MessageType -white_check_mark- Request
      ServiceID -white_check_mark- Your unique ID for this request, consisting of 1-10 alphanumeric characters. Must be unique within the last 48 hours for the terminal (POIID) being used.
      SaleID -white_check_mark- Your unique ID for the POS system component to send this request from.
      POIID -white_check_mark- The unique ID of the terminal to send this request to. Format: [device model]-[serial number].
    • The PaymentRequest object with:

      Parameter Required Description
      SaleData.SaleTransactionID -white_check_mark- An object with:
      • TransactionID: your reference to identify a payment. We recommend a unique value for each payment.
      • TimeStamp: date and time of the request in UTC format.
      SaleData.SaleReferenceID A unique reference that lets you identify payments that belong together.
      SaleData.SaleToAcquirerData -white_check_mark- Include the following parameters:
      PaymentTransaction.AmountsReq -white_check_mark- An object with:
      • Currency: the transaction currency.
      • RequestedAmount: the total for eligible items.
      PaymentData.CardAcquisitionReference -white_check_mark- An object referring to the card acquisition:
      • TimeStamp: the time stamp returned in the POIData.POITransactionID of the card acquisition response.
      • TransactionID: the transaction ID returned in the POIData.POITransactionID of the card acquisition response.
    • The healthcare fields in SaleData.SaleToAcquirerData with amounts in minor units, using the currency specified in PaymentTransaction.AmountsReq.Currency:

      Each sub-amount is required when it applies to the eligible items in this payment. This also applies to follow-up payments.

      Parameter Required Description
      healthcare.totalHealthcareValue -white_check_mark- The total FSA/HSA-eligible amount, in minor units. Must equal PaymentTransaction.AmountsReq.RequestedAmount converted to minor units. For example, 4500 for a RequestedAmount of 45.00 USD.
      healthcare.prescriptionValue
      Conditional
      The prescription (Rx) sub-amount, in minor units. This amount is included in healthcare.totalHealthcareValue.
      healthcare.visionPrescriptionValue
      Conditional
      The vision or optical sub-amount, in minor units. This amount is included in healthcare.totalHealthcareValue.
      healthcare.dentalValue
      Conditional
      The dental sub-amount, in minor units. This amount is included in healthcare.totalHealthcareValue.
      healthcare.otherMedicalValue
      Conditional
      The eligible medical amount not included in the prescription, vision, or dental sub-amounts, in minor units. This amount is included in healthcare.totalHealthcareValue.

    Adyen validates the healthcare amounts before authorizing the payment, and declines the payment if the amounts are invalid. The following rules apply:

    • healthcare.totalHealthcareValue must be greater than 0.
    • healthcare.totalHealthcareValue must not exceed the transaction amount.
    • The sum of the sub-amounts must not exceed healthcare.totalHealthcareValue.
    • healthcare.totalHealthcareValue is required when you include any sub-amount.

    You can pass the SaleToAcquirerData fields in either of the following formats. Both examples specify USD 45.00 in eligible healthcare amounts:

    • Option 1: Base64-encoded JSON. Create the following JSON object, encode it to Base64, and use the resulting string as SaleData.SaleToAcquirerData.

    • Option 2: Form-encoded key-value pairs. Use the following string as SaleData.SaleToAcquirerData.

    For more information about the formats, see Add information to a payment.

    The following example uses key-value pairs to send a USD 45.00 payment for eligible items. The ineligible items, if any, need a separate payment with another payment method.

  3. Check the PaymentResponse:

    • If Result is Success, the issuer approved the full eligible amount. AuthorizedAmount matches RequestedAmount.
      Successful responses do not include healthcare-specific fields in AdditionalResponse.
    • If Result is Partial, the issuer approved only part of the eligible amount:
      • Alert store staff that the shopper has not paid the full amount. The terminal also shows a warning, but staff can overlook it.
      • Use PaymentResult.AmountsResp.AuthorizedAmount to calculate the remaining amount, then make a follow-up payment.
      • If the shopper does not want to make the purchase because they do not want to pay the remaining amount, cancel the authorization to release the hold on the approved amount in the shopper's FSA/HSA account. To make sure you can cancel before the amount is captured, follow the partial authorization guidance and configure a capture delay.
    • If Result is Failure, check Response.ErrorCondition:

      • Invalid healthcare amounts: ErrorCondition is Refusal, and refusalReason in the decoded AdditionalResponse is InvalidFieldWithReason. The response does not say which amount is invalid: message is UNKNOWN. Check the amounts against the healthcare amount rules, and correct them before retrying.
      • Adyen unreachable: ErrorCondition is UnreachableHost, and refusalReason in the decoded AdditionalResponse is Failed to go online. The terminal cannot reach Adyen, and FSA/HSA payments cannot be completed offline. Have your POS app alert staff that an online connection is required, so they can offer another payment method.
      • Issuer unavailable: ErrorCondition is Refusal, and refusalReason in the decoded AdditionalResponse is Issuer unavailable. The FSA/HSA card cannot be used for this payment. Have your POS app alert staff, so they can offer another payment method.

      For other failures, see Handle responses.

    The following tabs show response examples for a full approval, a partial approval, and a decline for invalid healthcare amounts.

Make a follow-up payment for the remaining amount

You need a follow-up payment in the following cases:

  • The eligible amount is only partially paid: Collect the remaining eligible amount. Make a card acquisition request to identify the next card, then use an FSA/HSA or regular payment as appropriate.
  • The eligible amount is fully paid, but ineligible items remain: Make a regular Terminal API payment request for the ineligible items.
  • Both eligible and ineligible amounts remain: Make separate payments for the remaining eligible amount and the ineligible items.

To collect the remaining eligible amount:

  1. Calculate the remaining amount by subtracting the PaymentResult.AmountsResp.AuthorizedAmount in the partial payment response from the PaymentTransaction.AmountsReq.RequestedAmount in your initial payment request. You can also calculate the remaining amount from the posOriginalAmountValue and posAuthAmountValue keys in AdditionalResponse. Both values are in minor units.

  2. Make a new card acquisition request to check whether the card for the remaining eligible amount is an FSA/HSA card:

    • If the new card acquisition identifies the card as an FSA/HSA card, make an FSA/HSA payment for the remaining eligible amount. Include each sub-amount that applies to the remaining amount. The partial payment response returns only totals, not the amount authorized for each sub-amount, so your POS app determines the remaining sub-amounts. Their sum must not exceed the new healthcare.totalHealthcareValue.
    • If the new card acquisition does not identify the card as an FSA/HSA card, go to the next step.
  3. Make a regular Terminal API payment request for the remaining amount, specifying:

    • The standard SaleToPOIRequest.MessageHeader object, with MessageClass set to Service and MessageCategory set to Payment.

      Parameter Required Description
      ProtocolVersion -white_check_mark- 3.0
      MessageClass -white_check_mark- Service
      MessageCategory -white_check_mark- Payment
      MessageType -white_check_mark- Request
      ServiceID -white_check_mark- Your unique ID for this request, consisting of 1-10 alphanumeric characters. Must be unique within the last 48 hours for the terminal (POIID) being used.
      SaleID -white_check_mark- Your unique ID for the POS system component to send this request from.
      POIID -white_check_mark- The unique ID of the terminal to send this request to. Format: [device model]-[serial number].
    • The PaymentRequest object with:

      Parameter Required Description
      SaleData.SaleTransactionID -white_check_mark- An object with:
      • TransactionID: your reference to identify a payment. We recommend a unique value for each payment.
      • TimeStamp: date and time of the request in UTC format.
      SaleData.SaleReferenceID A unique reference that lets you identify payments that belong together, as described in partial authorization guidance. For example, Order-FSA-001-2 links to Order-FSA-001-1.
      SaleData.SaleToAcquirerData -white_check_mark- The AllowPartialAuthorisation tender option. Do not include healthcare fields for this regular payment.
      PaymentTransaction.AmountsReq -white_check_mark- An object with:
      • Currency: the transaction currency.
      • RequestedAmount: the remaining amount.
      PaymentData.CardAcquisitionReference
      Conditional
      Required if you performed a new card acquisition. An object with:
      • TimeStamp: the time stamp returned in the POIData.POITransactionID of the new card acquisition response.
      • TransactionID: the transaction ID returned in the POIData.POITransactionID of the new card acquisition response.

    The following example continues the example from Make an FSA/HSA payment. The issuer approved USD 25.00 of the USD 45.00 eligible amount, so the remaining amount is USD 20.00.

  4. Check the PaymentResponse. If Response.Result is Success, the remaining amount is paid. For other results, follow the partial authorization guidance or Handle responses.

    The following example shows the response for a follow-up payment that the issuer approved in full.

Testing

To verify your integration, test both successful and declined transactions. You can test your FSA/HSA integration with the following test cards. Both cards are healthcare-eligible.

Card number Card scheme Issuing country/region Expiry date Card security code
4001 2300 0000 0004 Visa US 12/2049 737
2292 2400 0000 0005 Mastercard US 12/2049 737

These card numbers are not available on a physical test card. To use them on a test terminal, enter the card details manually: in your card acquisition request, set CardAcquisitionTransaction.ForceEntryMode to Keyed, then enter the card number, expiry date, and security code on the terminal. Manual key entry must be enabled for your test account. See Manual Key Entry.

Then test the following scenarios.

  • Happy flow: Successful card acquisitions and payments, including a partial authorization. To trigger a partial authorization in test, use an amount ending in 139. For example, if you send a payment request for USD 41.39, the terminal authorizes USD 40.39. You then follow up with a payment for the remaining amount, in this case USD 1.00.
  • Unhappy flow: Declined and blocked payments.

Happy flow

Scenario Expected result
Card acquisition with an FSA/HSA-eligible Visa or Mastercard card healthcareIndicator is true in AdditionalResponse
Card acquisition with a standard (non-healthcare) card healthcareIndicator is absent from AdditionalResponse
Payment with healthcare.totalHealthcareValue and sub-amounts, within the transaction amount Result is Success
Payment with healthcare.totalHealthcareValue only, when no sub-amounts apply Result is Success
Payment where the FSA/HSA balance covers only part of healthcare.totalHealthcareValue Result is Partial, and AuthorizedAmount is less than RequestedAmount
Follow-up payment for the remaining amount, without healthcare fields Result is Success

Unhappy flow

To test how your POS app handles declined and blocked payments, use the following scenarios.

Scenario Expected result
Sum of sub-amounts exceeds healthcare.totalHealthcareValue Result is Failure, ErrorCondition is Refusal, and refusalReason in the decoded AdditionalResponse is InvalidFieldWithReason
healthcare.totalHealthcareValue exceeds the transaction amount Result is Failure, ErrorCondition is Refusal, and refusalReason in the decoded AdditionalResponse is InvalidFieldWithReason
Healthcare payment while the terminal cannot reach Adyen. For example, turn off Wi-Fi and mobile data on the terminal and send the request over a local connection, or turn off your Wi-Fi router after you send the request and before the payment is authorized. Result is Failure, ErrorCondition is UnreachableHost, and refusalReason in the decoded AdditionalResponse is Failed to go online

See also