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.

The mutation is idempotent. Generate a fresh idempotencyKey for each logical reversal, and replay the same key safely on retry.

Supported Benefits

Benefit type	Supported
HRA, FSA, DSA, LSA, and other non-HSA Benefits	Yes
HSA	Not yet

HSA Benefits return a BadRequestError. Contact [email protected] if you need to reverse an HSA funding before this is generally available. The request shape will not change when HSA reversal ships.

What you need

Required inputs:

• benefitId — the Individual's Benefit, the same value you passed to fundBenefitForIndividual.
• individualId — the Individual whose Benefit was funded.
• fundingTransactionId — the transactionId returned by the original fundBenefitForIndividual call. Persist it at funding time; it cannot be looked up by amount or date.
• 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 Individual's remaining available balance for the funding. Omit to reverse in full.
• description — a human-readable note recorded on the reversal. Defaults to Reversal [<fundingTransactionId>].

See the ReverseBenefitFundingForIndividualInput reference for the full schema.

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": "<transactionId from the original funding>",
        "idempotencyKey": "<your unique key>"
    }
}

A successful response:

{
    "data": {
        "reverseBenefitFundingForIndividual": {
            "benefitId": "<benefitId>",
            "individualId": "<individualId>",
            "fundingTransactionId": "<transactionId from the original funding>",
            "reversalTransactionId": "<new reversal transaction ID>"
        }
    }
}

On success, the Individual's available balance drops by the full original amount synchronously, reversalTransactionId identifies the new reversal transaction, and the reversed amount 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": "<transactionId from the original funding>",
        "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 cumulative reversal does not exceed the Individual's remaining available balance for that Benefit.

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

A reversal returns funds to the program account that credited the Benefit, and the Individual's available balance is updated synchronously. Onward return to the original funding source (employer or partner bank account) follows the partner's settlement configuration and happens outside this mutation.

Errors

Returns BadRequestError when:

• The funding cannot be located for the given Individual and Benefit. Covers both an unknown fundingTransactionId and one that does not belong to the supplied individualId/benefitId. Verify all three match the original fundBenefitForIndividual call.
• The reversal would overdraw the Individual's available balance — for example, reversing more than remains after prior spend or reversals. Reduce amount or omit it to reverse only what remains.
• amount is zero, negative, or not USD. Amounts must be positive and denominated in USD.
• The Benefit is an HSA. HSA reversal is not yet supported via this API.

Unexpected failures return InternalServerError; retry safely with the same idempotencyKey.