Create Refund | Truemed

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

Request Notes

The amount requested must be less than or equal to the total amount that the payment was originally created with.

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.
Across all lines, the totals must not sum above amount.
The totals may sum below amount. Truemed applies the remainder across the session’s captures.

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 across the session’s captures.

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 HSA/FSA share of a refund from the lines you itemize:

When every itemized line is HSA/FSA-eligible, the whole amount returns to the HSA/FSA card.
Otherwise Truemed pro-rates amount by the eligible ratio of the itemized lines.
Truemed caps the result at what the order captured to the HSA/FSA card, minus what earlier refunds already returned there. A refund never sends more to the HSA/FSA card than the order put there.

A refund sent without item_details returns to the HSA/FSA card first, up to the remaining eligible amount. The same amount on the same order therefore splits differently depending on whether you send item_details. Send item_details when you want the split to follow specific lines.

A refund with no itemizable line behind it, such as returning shipping on its own, carries no item_details and so takes the HSA/FSA-first path.

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.
message:
- Indication of one of the following:
  - Which field was missing
  - Details on how the amount was invalid
  - Invalid payment id

Use this endpoint to refund payments Truemed has already processed on your behalf. Partial refunds are supported. ## Request Notes <Warning> The amount requested must be less than or equal to the total amount that the payment was originally created with. </Warning> ### 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](/api-reference/payment-sessions/retrieve-payment-session). - Across all lines, the totals must not sum above `amount`. - The totals may sum below `amount`. Truemed applies the remainder across the session's captures. ### 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 across the session's captures. 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 HSA/FSA share of a refund from the lines you itemize: - When every itemized line is HSA/FSA-eligible, the whole `amount` returns to the HSA/FSA card. - Otherwise Truemed pro-rates `amount` by the eligible ratio of the itemized lines. - Truemed caps the result at what the order captured to the HSA/FSA card, minus what earlier refunds already returned there. A refund never sends more to the HSA/FSA card than the order put there. A refund sent without `item_details` returns to the HSA/FSA card first, up to the remaining eligible amount. The same `amount` on the same order therefore splits differently depending on whether you send `item_details`. Send `item_details` when you want the split to follow specific lines. A refund with no itemizable line behind it, such as returning shipping on its own, carries no `item_details` and so takes the HSA/FSA-first path. ## 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. - `message`: - Indication of one of the following: - Which field was missing - Details on how the amount was invalid - Invalid payment id

Authentication

x-truemed-api-keystring

Sales channel API key for merchant server-to-server authentication

Request

Request body for CreateRefundRequest

amountintegerRequired

The amount you wish to refund in cents. Cannot be greater than the total_amount originally charged.

idempotency_keystringRequired

Allows the endpoint to be called multiple times, and must be unique to the refund request.

item_detailslist of objectsRequired

The items to refund. Truemed derives the HSA/FSA share of the refund from these lines: the whole amount returns to the HSA/FSA card when every line is eligible, and otherwise Truemed pro-rates amount by their eligible ratio. Omit this field and Truemed returns to the HSA/FSA card first, up to the remaining eligible amount.

payment_idstringRequired

The id returned to the partner by Truemed in response to a create_payment_session request.

reasonenumRequired

Why you are initiating this refund request: customer_request - the customer requested a refund; fraudulent - the payment was fraudulent; duplicate_payment - the user checked out with HSA/FSA multiple times for one purchase.

One of:

customer_request — The refund was requested by the customer.
duplicate_payment — The charge was a duplicate.
fraudulent — The charge was fraudulent; this feeds the fraud signal.

Allowed values:

capture_idstring or nullOptional

The id of the capture to refund, from captures[].id in the payment session status. Only required if the session has more than one capture; if omitted, the refund is applied across the session’s captures.

Response

Successful response

refund_idstring

The unique ID for this refund. Multiple refunds can be associated with a single payment, in the case of partial refunds.

Errors

400

Bad Request Error

404

Not Found Error

405

Method Not Allowed Error

500

Internal Server Error

501

Not Implemented Error

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

Request Notes

The amount requested must be less than or equal to the total amount that the payment was originally created with.

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.
Across all lines, the totals must not sum above amount.
The totals may sum below amount. Truemed applies the remainder across the session’s captures.

Order-level charges and discounts

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 HSA/FSA share of a refund from the lines you itemize:

When every itemized line is HSA/FSA-eligible, the whole amount returns to the HSA/FSA card.
Otherwise Truemed pro-rates amount by the eligible ratio of the itemized lines.
Truemed caps the result at what the order captured to the HSA/FSA card, minus what earlier refunds already returned there. A refund never sends more to the HSA/FSA card than the order put there.

A refund with no itemizable line behind it, such as returning shipping on its own, carries no item_details and so takes the HSA/FSA-first path.

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.
message:
- Indication of one of the following:
  - Which field was missing
  - Details on how the amount was invalid
  - Invalid payment id