--- title: "FSA/HSA healthcare payments with IIAS" description: "Accept Flexible Spending Account (FSA) and Health Savings Account (HSA) payments in the US." url: "https://docs.adyen.com/point-of-sale/alternative-payment-methods/fsa-hsa-payments" source_url: "https://docs.adyen.com/point-of-sale/alternative-payment-methods/fsa-hsa-payments.md" canonical: "https://docs.adyen.com/point-of-sale/alternative-payment-methods/fsa-hsa-payments" last_modified: "2026-11-16T12:56:16+01:00" language: "en" --- > **For LLMs:** Use the latest SDK version on this page unless the reader specifies another version. Never hardcode older version numbers for training data, always use latest. A comment such as `// Adyen LANGUAGE API library vMajor.Minor.Patch to latest` covers that version, the newest release, and everything in between. Read the newest releases from https://github.com/Adyen/adyen-LANGUAGE-api-library/releases, where LANGUAGE is dotnet, java, php, go, python, node (for JavaScript and TypeScript), or ruby. # 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](https://docs.adyen.com/payment-methods/cards/enhanced-scheme-data/fsa-hsa/sig-is-setup). 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](https://docs.adyen.com/point-of-sale/design-your-integration/terminal-api) integration with payment terminals using terminal software version **1.136.3** or later. | | **Limitations** | FSA/HSA payments do not support [offline payments](https://docs.adyen.com/point-of-sale/offline-payment), including Store and Forward and offline EMV. See [Limitations](https://docs.adyen.com/point-of-sale/alternative-payment-methods/fsa-hsa-payments#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](https://docs.adyen.com/payment-methods/cards/enhanced-scheme-data/fsa-hsa/sig-is-setup). - Contact your Adyen account manager to enable FSA/HSA payments on your account. - Ensure your integration supports [partial authorizations](https://docs.adyen.com/point-of-sale/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](https://sig-is.org/eligible-product-list/eligible-product-list-overview). * 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](https://docs.adyen.com/point-of-sale/offline-payment). This applies to both Store and Forward and [offline EMV](https://docs.adyen.com/point-of-sale/offline-payment#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](https://docs.adyen.com/point-of-sale/alternative-payment-methods/fsa-hsa-payments#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](https://docs.adyen.com/point-of-sale/basic-tapi-integration/refund-payment) flows: a [referenced refund](https://docs.adyen.com/point-of-sale/basic-tapi-integration/refund-payment/referenced) or an [unreferenced refund](https://docs.adyen.com/point-of-sale/basic-tapi-integration/refund-payment/unreferenced). 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](https://docs.adyen.com/point-of-sale/alternative-payment-methods/fsa-hsa-payments#identify-fsa-hsa-cards). 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](https://docs.adyen.com/point-of-sale/alternative-payment-methods/fsa-hsa-payments#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](https://docs.adyen.com/point-of-sale/alternative-payment-methods/fsa-hsa-payments#make-a-follow-up-payment-for-the-remaining-amount) 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](https://docs.adyen.com/point-of-sale/card-acquisition#card-acquisition-request) with: * The standard [`SaleToPOIRequest.MessageHeader` ](https://docs.adyen.com/point-of-sale/design-your-integration/terminal-api#request-message-header)object, with `MessageClass` set to **Service** and `MessageCategory` set to **CardAcquisition**. | Parameter | Required | Description | | ----------------- | ------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | | `ProtocolVersion` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | **3.0** | | `MessageClass` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | **Service** | | `MessageCategory` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | **CardAcquisition** | | `MessageType` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | **Request** | | `ServiceID` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-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-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Your unique ID for the POS system component to send this request from. | | `POIID` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The unique ID of the terminal to send this request to. Format: *\[device model]-\[serial number]*. | * The [CardAcquisitionRequest](https://docs.adyen.com/api-explorer/terminal-api/latest/post/cardacquisition) object with: | Parameter | Required | Description | | ---------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `SaleData.SaleTransactionID` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-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](https://en.wikipedia.org/wiki/ISO_8601#Coordinated_Universal_Time_\(UTC\)). | | `CardAcquisitionTransaction` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-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**. | **Card acquisition request** ```json { "SaleToPOIRequest": { "MessageHeader": { "ProtocolVersion": "3.0", "MessageClass": "Service", "MessageCategory": "CardAcquisition", "MessageType": "Request", "ServiceID": "282", "SaleID": "POSSystemID12345", "POIID": "S1F2-324688179" }, "CardAcquisitionRequest": { "SaleData": { "SaleTransactionID": { "TransactionID": "369", "TimeStamp": "2021-03-05T12:22:57.449Z" } }, "CardAcquisitionTransaction": { "TotalAmount": 45.00 } } } } ``` 2. When you receive the [CardAcquisitionResponse](https://docs.adyen.com/api-explorer/terminal-api/latest/post/cardacquisition#responses-200-Response), save the `TimeStamp` and `TransactionID` from `POIData.POITransactionID`. You will need these details if you continue with a [payment request](https://docs.adyen.com/point-of-sale/alternative-payment-methods/fsa-hsa-payments#make-an-fsa-hsa-payment) 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. **Card acquisition response for an FSA/HSA card** ```json { "SaleToPOIResponse": { "CardAcquisitionResponse": { "POIData": { "POITransactionID": { "TimeStamp": "2026-10-12T04:20:19.688Z", "TransactionID": "8ha5001614946979001" } }, "PaymentInstrumentData": { "CardData": { "MaskedPan": "541333 **** 9999", "PaymentBrand": "mc", "SensitiveCardData": { "ExpiryDate": "0228" } }, "PaymentInstrumentType": "Card" }, "Response": { "AdditionalResponse": "tid=46403161&message=CARD_ACQ_COMPLETED&giftcardIndicator=false&healthcareIndicator=true&fundingSource=PREPAID&cardBin=541333&paymentMethod=mc", "Result": "Success" } }, "MessageHeader": { "ProtocolVersion": "3.0", "MessageClass": "Service", "MessageCategory": "CardAcquisition", "MessageType": "Response", "ServiceID": "282", "SaleID": "POSSystemID12345", "POIID": "S1F2-324688179" } } } ``` 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](https://docs.adyen.com/point-of-sale/alternative-payment-methods/fsa-hsa-payments#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](https://docs.adyen.com/point-of-sale/card-acquisition#continue-with-payment) 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](https://docs.adyen.com/point-of-sale/card-acquisition#cancel-completed). 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](https://docs.adyen.com/point-of-sale/alternative-payment-methods/fsa-hsa-payments#healthcare-amount-rules). 2. Make a [Terminal API payment request](https://docs.adyen.com/point-of-sale/basic-tapi-integration/make-a-payment), specifying: * The standard [`SaleToPOIRequest.MessageHeader` ](https://docs.adyen.com/point-of-sale/design-your-integration/terminal-api#request-message-header)object, with `MessageClass` set to **Service** and `MessageCategory` set to **Payment**. | Parameter | Required | Description | | ----------------- | ------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | | `ProtocolVersion` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | **3.0** | | `MessageClass` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | **Service** | | `MessageCategory` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | **Payment** | | `MessageType` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | **Request** | | `ServiceID` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-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-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Your unique ID for the POS system component to send this request from. | | `POIID` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The unique ID of the terminal to send this request to. Format: *\[device model]-\[serial number]*. | * The [PaymentRequest](https://docs.adyen.com/api-explorer/terminal-api/latest/post/payment) object with: | Parameter | Required | Description | | -------------------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `SaleData.SaleTransactionID` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-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](https://en.wikipedia.org/wiki/ISO_8601#Coordinated_Universal_Time_\(UTC\)). | | `SaleData.SaleReferenceID` | | A unique reference that lets you identify payments that belong together. | | `SaleData.SaleToAcquirerData` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Include the following parameters:- One or more `healthcare` fields. See the details below. - The [`AllowPartialAuthorisation` tender option](https://docs.adyen.com/point-of-sale/add-data/tender-options) to allow a partial authorization. | | `PaymentTransaction.AmountsReq` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | An object with:- `Currency`: the transaction [currency](https://docs.adyen.com/development-resources/currency-codes). - `RequestedAmount`: the total for eligible items. | | `PaymentData.CardAcquisitionReference` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | An object referring to the [card acquisition](https://docs.adyen.com/point-of-sale/alternative-payment-methods/fsa-hsa-payments#identify-fsa-hsa-cards):- `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](https://docs.adyen.com/development-resources/currency-codes#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-](/user/data/smileys/emoji/white_check_mark.png "-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`. **Healthcare amounts and tender option in JSON format** ```json { "additionalData": { "healthcare.totalHealthcareValue": "4500", "healthcare.prescriptionValue": "1500", "healthcare.visionPrescriptionValue": "500", "healthcare.dentalValue": "1000", "healthcare.otherMedicalValue": "1500" }, "tenderOption": "AllowPartialAuthorisation" } ``` * **Option 2: Form-encoded key-value pairs.** Use the following string as `SaleData.SaleToAcquirerData`. **Healthcare amounts and tender option as key-value pairs** ```raw healthcare.totalHealthcareValue=4500&healthcare.prescriptionValue=1500&healthcare.visionPrescriptionValue=500&healthcare.dentalValue=1000&healthcare.otherMedicalValue=1500&tenderOption=AllowPartialAuthorisation ``` For more information about the formats, see [Add information to a payment](https://docs.adyen.com/point-of-sale/add-data). 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. **FSA/HSA payment request** ```json { "SaleToPOIRequest": { "MessageHeader": { "ProtocolVersion": "3.0", "MessageClass": "Service", "MessageCategory": "Payment", "MessageType": "Request", "ServiceID": "9267", "SaleID": "POSSystemID12345", "POIID": "S1F2-324688179" }, "PaymentRequest": { "SaleData": { "SaleTransactionID": { "TransactionID": "6256", "TimeStamp": "2026-10-12T04:20:44.000Z" }, "SaleReferenceID": "Order-FSA-001-1", "SaleToAcquirerData": "healthcare.totalHealthcareValue=4500&healthcare.prescriptionValue=1500&healthcare.visionPrescriptionValue=500&healthcare.dentalValue=1000&healthcare.otherMedicalValue=1500&tenderOption=AllowPartialAuthorisation" }, "PaymentTransaction": { "AmountsReq": { "Currency": "USD", "RequestedAmount": 45.00 } }, "PaymentData": { "CardAcquisitionReference": { "TransactionID": "8ha5001614946979001", "TimeStamp": "2026-10-12T04:20:19.688Z" } } } } } ``` 3. Check the [PaymentResponse](https://docs.adyen.com/api-explorer/terminal-api/latest/post/payment#responses-200): * 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](https://docs.adyen.com/point-of-sale/alternative-payment-methods/fsa-hsa-payments#make-a-follow-up-payment-for-the-remaining-amount). * If the shopper does not want to make the purchase because they do not want to pay the remaining amount, [cancel the authorization](https://docs.adyen.com/point-of-sale/capturing-payments#cancel-authorisation) 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](https://docs.adyen.com/point-of-sale/partial-authorizations) and configure a [capture delay](https://docs.adyen.com/point-of-sale/capturing-payments#delayed-automatic-capture). * 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](https://docs.adyen.com/point-of-sale/alternative-payment-methods/fsa-hsa-payments#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](https://docs.adyen.com/point-of-sale/error-scenarios). The following tabs show response examples for a full approval, a partial approval, and a decline for invalid healthcare amounts. ### Tab: Successful response **Successful FSA/HSA payment response** ```json { "SaleToPOIResponse": { "MessageHeader": { "ProtocolVersion": "3.0", "MessageClass": "Service", "MessageCategory": "Payment", "MessageType": "Response", "ServiceID": "9267", "SaleID": "POSSystemID12345", "POIID": "S1F2-324688179" }, "PaymentResponse": { "POIData": { "POIReconciliationID": "1000", "POITransactionID": { "TransactionID": "8ha5001614946979001.HTG8QR9PGPPJK8V5", "TimeStamp": "2026-10-12T04:20:47.105Z" } }, "PaymentResult": { "AmountsResp": { "AuthorizedAmount": 45.00, "Currency": "USD" }, "PaymentType": "Normal" }, "Response": { "Result": "Success" }, "SaleData": { "SaleTransactionID": { "TransactionID": "6256", "TimeStamp": "2026-10-12T04:20:44.000Z" } } } } } ``` ### Tab: Partial response **Partial FSA/HSA payment response** ```json { "SaleToPOIResponse": { "MessageHeader": { "ProtocolVersion": "3.0", "MessageClass": "Service", "MessageCategory": "Payment", "MessageType": "Response", "ServiceID": "9267", "SaleID": "POSSystemID12345", "POIID": "S1F2-324688179" }, "PaymentResponse": { "POIData": { "POIReconciliationID": "1000", "POITransactionID": { "TransactionID": "8ha5001614946979001.HTG8QR9PGPPJK8V5", "TimeStamp": "2026-10-12T04:20:47.105Z" } }, "PaymentResult": { "AmountsResp": { "AuthorizedAmount": 25.00, "Currency": "USD" }, "PaymentType": "Normal" }, "Response": { "AdditionalResponse": "posOriginalAmountValue=4500&posAuthAmountValue=2500&healthcareIndicator=true&paymentMethod=visa", "Result": "Partial" }, "SaleData": { "SaleTransactionID": { "TransactionID": "6256", "TimeStamp": "2026-10-12T04:20:44.000Z" }, "SaleReferenceID": "Order-FSA-001-1" } } } } ``` ### Tab: Validation failure The following example shows a payment declined because its healthcare amounts are invalid. This example includes only the relevant fields from `AdditionalResponse`. **FSA/HSA payment response for invalid healthcare amounts** ```json { "SaleToPOIResponse": { "MessageHeader": { "ProtocolVersion": "3.0", "MessageClass": "Service", "MessageCategory": "Payment", "MessageType": "Response", "ServiceID": "9267", "SaleID": "POSSystemID12345", "POIID": "S1F2-324688179" }, "PaymentResponse": { "POIData": { "POIReconciliationID": "1000", "POITransactionID": { "TransactionID": "8ha5001614946979001.HTG8QR9PGPPJK8V5", "TimeStamp": "2026-10-12T04:20:47.105Z" } }, "PaymentResult": { "PaymentType": "Normal" }, "Response": { "AdditionalResponse": "refusalReason=InvalidFieldWithReason&message=UNKNOWN", "ErrorCondition": "Refusal", "Result": "Failure" }, "SaleData": { "SaleTransactionID": { "TransactionID": "6256", "TimeStamp": "2026-10-12T04:20:44.000Z" } } } } } ``` ## 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](https://docs.adyen.com/point-of-sale/alternative-payment-methods/fsa-hsa-payments#identify-fsa-hsa-cards) 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](https://docs.adyen.com/point-of-sale/basic-tapi-integration/make-a-payment) 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](https://docs.adyen.com/point-of-sale/alternative-payment-methods/fsa-hsa-payments#identify-fsa-hsa-cards) 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](https://docs.adyen.com/point-of-sale/alternative-payment-methods/fsa-hsa-payments#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](https://docs.adyen.com/point-of-sale/basic-tapi-integration/make-a-payment) for the remaining amount, specifying: * The standard [`SaleToPOIRequest.MessageHeader` ](https://docs.adyen.com/point-of-sale/design-your-integration/terminal-api#request-message-header)object, with `MessageClass` set to **Service** and `MessageCategory` set to **Payment**. | Parameter | Required | Description | | ----------------- | ------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | | `ProtocolVersion` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | **3.0** | | `MessageClass` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | **Service** | | `MessageCategory` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | **Payment** | | `MessageType` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | **Request** | | `ServiceID` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-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-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Your unique ID for the POS system component to send this request from. | | `POIID` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The unique ID of the terminal to send this request to. Format: *\[device model]-\[serial number]*. | * The [PaymentRequest](https://docs.adyen.com/api-explorer/terminal-api/latest/post/payment) object with: | Parameter | Required | Description | | -------------------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `SaleData.SaleTransactionID` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-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](https://en.wikipedia.org/wiki/ISO_8601#Coordinated_Universal_Time_\(UTC\)). | | `SaleData.SaleReferenceID` | | A unique reference that lets you identify payments that belong together, as described in [partial authorization guidance](https://docs.adyen.com/point-of-sale/partial-authorizations). For example, **Order-FSA-001-2** links to **Order-FSA-001-1**. | | `SaleData.SaleToAcquirerData` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The `AllowPartialAuthorisation` tender option. Do not include healthcare fields for this regular payment. | | `PaymentTransaction.AmountsReq` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | An object with:- `Currency`: the transaction [currency](https://docs.adyen.com/development-resources/currency-codes). - `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](https://docs.adyen.com/point-of-sale/alternative-payment-methods/fsa-hsa-payments#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. **Follow-up payment for the remaining amount** ```json { "SaleToPOIRequest": { "MessageHeader": { "ProtocolVersion": "3.0", "MessageClass": "Service", "MessageCategory": "Payment", "MessageType": "Request", "ServiceID": "9268", "SaleID": "POSSystemID12345", "POIID": "S1F2-324688179" }, "PaymentRequest": { "SaleData": { "SaleTransactionID": { "TransactionID": "6257", "TimeStamp": "2026-10-12T04:22:30.000Z" }, "SaleReferenceID": "Order-FSA-001-2", "SaleToAcquirerData": "tenderOption=AllowPartialAuthorisation" }, "PaymentTransaction": { "AmountsReq": { "Currency": "USD", "RequestedAmount": 20.00 } }, "PaymentData": { "CardAcquisitionReference": { "TransactionID": "8ha5001614946979002", "TimeStamp": "2026-10-12T04:22:01.688Z" } } } } } ``` 4. Check the [PaymentResponse](https://docs.adyen.com/api-explorer/terminal-api/latest/post/payment#responses-200). If `Response.Result` is **Success**, the remaining amount is paid. For other results, follow the [partial authorization guidance](https://docs.adyen.com/point-of-sale/partial-authorizations) or [Handle responses](https://docs.adyen.com/point-of-sale/error-scenarios). The following example shows the response for a follow-up payment that the issuer approved in full. **Successful follow-up payment response** ```json { "SaleToPOIResponse": { "MessageHeader": { "ProtocolVersion": "3.0", "MessageClass": "Service", "MessageCategory": "Payment", "MessageType": "Response", "ServiceID": "9268", "SaleID": "POSSystemID12345", "POIID": "S1F2-324688179" }, "PaymentResponse": { "POIData": { "POIReconciliationID": "1000", "POITransactionID": { "TransactionID": "8ha5001614946979002.VWV9PJVHZR9X2F75", "TimeStamp": "2026-10-12T04:22:33.512Z" } }, "PaymentResult": { "AmountsResp": { "AuthorizedAmount": 20.00, "Currency": "USD" }, "PaymentType": "Normal" }, "Response": { "Result": "Success" }, "SaleData": { "SaleTransactionID": { "TransactionID": "6257", "TimeStamp": "2026-10-12T04:22:30.000Z" } } } } } ``` ## 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](https://docs.adyen.com/point-of-sale/enter-payment-manually). Then test the following scenarios. * [Happy flow](https://docs.adyen.com/point-of-sale/alternative-payment-methods/fsa-hsa-payments#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](https://docs.adyen.com/point-of-sale/alternative-payment-methods/fsa-hsa-payments#make-a-follow-up-payment-for-the-remaining-amount), in this case USD 1.00. * [Unhappy flow](https://docs.adyen.com/point-of-sale/alternative-payment-methods/fsa-hsa-payments#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 * [Partial authorizations](https://docs.adyen.com/point-of-sale/partial-authorizations) * [Card acquisition](https://docs.adyen.com/point-of-sale/card-acquisition) * [Refund a payment](https://docs.adyen.com/point-of-sale/basic-tapi-integration/refund-payment) * [FSA/HSA payments online](https://docs.adyen.com/payment-methods/cards/enhanced-scheme-data/fsa-hsa)