Reversing a funding
Use reverseBenefitFundingForIndividual to undo a funding issued in error — wrong amount, wrong individual, or duplicate. The reversal links to the original funding transaction, decreases the Individual's available balance, and is recorded as a reversal of the prior credit. Negative-amount calls to fundBenefitForIndividual are rejected; reversal is the only Partner API path to undo a specific prior funding.
You can reverse two kinds of funding: one you made with fundBenefitForIndividual, and a contribution First Dollar pulled from payroll. Other credits on the Individual's Account, such as the Individual's own contribution, interest, or a Card refund, are not fundings. Do not pass them to this mutation.
The mutation is idempotent. Generate a fresh idempotencyKey for each logical reversal, and replay the same key safely on retry.
Supported Benefits
Reversal works for every Benefit type, including HSA. The request and response are the same for all of them. For notes specific to HSA Benefits, see HSA funding.
What you need
Required inputs:
benefitId— the Benefit that was funded.individualId— the Individual whose Benefit was funded.fundingTransactionId— theidof the funding's Transaction. For a funding you made, this is thetransactionIdthatfundBenefitForIndividualreturned. For any funding, including contributions First Dollar pulled from payroll, you can also look it up in the Individual's transactions. Both give the same ID.idempotencyKey— a unique value of your choosing. Repeated calls with the same key return the same result without applying the reversal a second time.
Optional:
amount— partial reversal amount as a MoneyInput, for example{ "currency": "USD", "lowestDenominationAmount": 2500 }for $25.00. Must be positive and no greater than the part of the funding not yet reversed. For an HSA Benefit, it also cannot exceed the Individual's available balance. Omit it to reverse the full original funding amount. After a partial reversal, pass the remaining amount explicitly, because an omittedamountstill asks for the full original amount and is rejected.description— a human-readable note recorded on the reversal. Defaults toReversal [<fundingTransactionId>].
See the ReverseBenefitFundingForIndividualInput reference for the full schema.
Find a funding's transaction ID
Each funding appears as a credit (a positive amount) in the transactions of the Individual's Account for the Benefit. That Transaction's id is the fundingTransactionId. Use date, amount and description to pick the right credit. Pass only the ID of a funding: a credit from fundBenefitForIndividual or a contribution First Dollar pulled from payroll. A debit, such as Card spend or a prior reversal, is rejected. Other credits, such as the Individual's own contribution, interest, or a Card refund, are not fundings, so do not pass their IDs.
query FundingTransactions($where: IndividualsFilterInput!) {
individuals(where: $where) {
... on IndividualsResults {
nodes {
id
healthWallet {
accounts {
benefit {
id
}
transactions {
nodes {
id
date
description
amount {
currency
lowestDenominationAmount
}
}
pageInfo {
hasNextPage
endCursor
}
}
}
}
}
}
}
}
See Balance & Transactions for the full query.
Reverse a funding in full
mutation ReverseBenefitFundingForIndividual($input: ReverseBenefitFundingForIndividualInput!) {
reverseBenefitFundingForIndividual(input: $input) {
... on ReverseBenefitFundingForIndividualResult {
benefitId
individualId
fundingTransactionId
reversalTransactionId
}
... on BadRequestError {
message
code
retryable
}
... on InternalServerError {
message
code
retryable
}
}
}
Variables:
{
"input": {
"benefitId": "<benefitId>",
"individualId": "<individualId>",
"fundingTransactionId": "<the funding's transaction ID>",
"idempotencyKey": "<your unique key>"
}
}
A successful response:
{
"data": {
"reverseBenefitFundingForIndividual": {
"benefitId": "<benefitId>",
"individualId": "<individualId>",
"fundingTransactionId": "<the funding's transaction ID>",
"reversalTransactionId": "<new reversal transaction ID>"
}
}
}
On success, the Individual's available balance drops by the full original amount synchronously and reversalTransactionId identifies the new reversal transaction. For non-HSA Benefits, the reversed amount also restores headroom against the Benefit's contribution limits — partners can fund again up to the original cap.
Reverse part of a funding
Include amount to reverse a portion. The remainder stays available to the Individual.
{
"input": {
"benefitId": "<benefitId>",
"individualId": "<individualId>",
"fundingTransactionId": "<the funding's transaction ID>",
"amount": { "currency": "USD", "lowestDenominationAmount": 2500 },
"idempotencyKey": "<your unique key>",
"description": "Partial reversal - overcharged $25"
}
}
Issue multiple partial reversals against the same fundingTransactionId, each with its own idempotencyKey, as long as the total reversed does not exceed the original funding amount. For an HSA Benefit, each reversal must also leave the Individual's available balance at zero or above.
To reverse the rest of a funding after a partial reversal, pass the remaining amount as amount. If you omit amount, the request asks for the full original amount again, which exceeds what remains, and is rejected.
Idempotency
idempotencyKey is required. Replaying a request with the same key — for example, after a network error — returns the same reversalTransactionId and applies the reversal exactly once.
Use a fresh idempotencyKey for each distinct reversal, including successive partial reversals of the same funding.
Where reversed funds go
The Individual's available balance is updated synchronously.
For non-HSA Benefits, reversed funds are returned to the funding source for the Benefit. Any later return of funds further upstream is handled separately and is not part of this mutation.
For HSA Benefits, the reversal withdraws the funds from the Individual's HSA, and First Dollar's treasury team manages them from there. To trace reversed HSA funds, contact [email protected].
Errors
Returns BadRequestError when:
- The funding cannot be located for the given Individual and Benefit. Covers an unknown
fundingTransactionId, one that identifies a debit rather than a funding, and one that does not belong to the suppliedindividualId/benefitId. Verify that all three refer to the same funding. - The reversal would overdraw the Individual's available balance (HSA Benefits). For example, the Individual has already spent part of the funding. Pass a smaller
amount, no more than the Individual's available balance. An omittedamountasks for the full original amount, so it is rejected here too. amountis zero, negative, or not USD. Amounts must be positive and denominated in USD.- The reversal would exceed the original funding. The total of all reversals against one
fundingTransactionIdcannot exceed the amount originally funded. After a partial reversal, pass no more than the part not yet reversed. - The HSA funding was made before the HSA moved to its current bank. A funding from before the move cannot be reversed through the API. Contact [email protected].
Unexpected failures return InternalServerError; retry safely with the same idempotencyKey.