Create Refund

Use this endpoint to refund payments Truemed has already processed on your behalf. Partial refunds are supported.

Request Notes

Itemizing a refund

amount is what Truemed refunds. item_details tells Truemed how to attribute that amount across the order’s lines.

• Set each item_details[].total to the amount you are refunding for that line. It cannot exceed that item’s total_refundable from Get Payment Status.
• Set item_details[].quantity to 0 to refund dollars without units. Use this for the rest of a line after an earlier partial refund already returned its units. The dollars stay on that line, and its eligibility determines how Truemed splits the refund across cards.
• Across all lines, the totals must not sum above amount.
• The totals may sum below amount. Truemed applies the remainder to the capture the refund targets.

Multi-capture sessions

Each refund applies to one capture. Use the capture_id from the capture response, or captures[].id from Get Payment Status.

• Pass capture_id when the session has more than one capture, or when any capture did not complete.
• You can refund a capture while the session is still partially_captured. Every capture has already charged the customer, so the refund returns that money and the uncaptured remainder stays held for later captures. While the session is partially_captured, pass capture_id. Truemed rejects the refund if another capture is still processing.
• To refund shipping or another amount with no line item, target the capture that charged it.
• To refund more than one capture, send one refund per capture.
• A refund never frees up authorization. Captures after a refund are still limited to the amount that was never captured.

Order-level charges and discounts

create_payment_session accepts an amount_details object at the order level, carrying charges and discounts that belong to the order rather than to any single line. Shipping and tax behave the same way.

Because Truemed tracks total_refundable per item, an order-level amount appears in no item’s total_refundable. For a full refund, set amount to the full captured amount and each item_details[].total to that item’s total_refundable. The item totals then sum below amount by the order-level amount, and Truemed applies that remainder to the capture the refund targets.

On a partial refund, amount sets how much of an order-level charge returns. To return none of it, set amount equal to the sum of your item totals.

How much returns to the HSA/FSA card

Truemed derives the eligible amount of a refund from the lines you itemize:

• When every itemized line qualifies for HSA/FSA spending, the whole amount counts as eligible.
• Otherwise Truemed pro-rates amount by the eligible ratio of the itemized lines.
• Eligible spending that the regular card paid returns there first. The remaining eligible amount returns to the HSA/FSA card, and the rest returns to the regular card.
• Truemed caps each card’s share at its remaining refundable balance. If the regular card cannot cover its share, the shortfall returns to the HSA/FSA card within that card’s refundable balance.

Returning an amount that belongs to no item

Some refunds have no line behind them: a goodwill credit for a late delivery, or shipping returned on its own. Omit item_details and send amount alone. An empty item_details list is the same request.

When a refund names no items, Truemed treats the refund as HSA/FSA-eligible first, up to the remaining eligible amount. Eligible spending that the regular card paid returns there first. Truemed then uses the HSA/FSA card’s refundable balance and returns the rest to the regular card. Name the lines in item_details to allocate the refund by those lines’ eligible share.

Two caps apply either way, both measured against earlier refunds. amount cannot exceed what the order still has left to return. The refund’s eligible amount cannot exceed the eligible amount still outstanding. Once no eligible amount remains, later refunds go to the regular card first, subject to each card’s refundable balance.

Itemizing is still worth doing when the refund does follow specific lines. It keeps each line’s remaining refundable amount accurate and puts the refund against that line on the customer’s receipt. Without it the refund is allocated correctly and capped the same way, but it appears as an order-level adjustment and the individual lines keep their original refundable amounts.

Response Notes

Bad Request

HTTP Status: 400

If a field is missing or the request is otherwise can’t be processed, we’ll return a 400 with the following fields:

• error - can be one of:
  • MissingField: one of the required fields is not present in the request
  • AmountInvalid: the amount field is negative, 0, or greater than the amount remaining available to refund on the payment
  • InvalidPaymentId: requesting to refund a payment that does not exist
  • ChargeDisputed: Payment session has a pending dispute. Can’t refund until the dispute is resolved. Lost disputes reduce the remaining refundable amount but no longer block refunds of the undisputed remainder.
  • NoSessionCaptures: The payment session can’t be refunded because there haven’t been any funds captured.
  • ValidationError: Truemed does not allow the refund in the session’s current state. For example, capture_id is missing on a session with more than one capture, on a session with a capture that did not complete, or on a partially_captured session. Other causes: another capture or a void is still processing, or the session collected no funds.
• message:
  • Indication of one of the following:
    • Which field was missing
    • Details on how the amount was invalid
    • Invalid payment id