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.

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> ## 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

A list of items to be refunded.

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.

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.

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

$	curl -X POST https://dev-api.truemed.com/payments/v1/refund \
>	-H "x-truemed-api-key: <apiKey>" \
>	-H "Content-Type: application/json" \
>	-d '{
>	"amount": 1,
>	"idempotency_key": "string",
>	"item_details": [
>	{
>	"item_id": "string",
>	"quantity": 1,
>	"total": 1
>	}
>	],
>	"payment_id": "string",
>	"reason": "customer_request"
>	}'