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 disputes. Can’t refund until disputes are settled.
- 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 disputes. Can't refund until disputes are settled. - `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.

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.

Allowed values:

item_detailslist of objects or nullOptional

A list of items to be refunded.

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

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 disputes. Can’t refund until disputes are settled.
- 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

1	import requests
2
3	url = "https://dev-api.truemed.com/payments/v1/refund"
4
5	payload = {
6	"amount": 2500,
7	"idempotency_key": "a3f47b9e-8c2d-4f1a-9b7e-2d5f6c8a9e12",
8	"payment_id": "pay_9876543210abcdef",
9	"reason": "customer_request"
10	}
11	headers = {
12	"x-truemed-api-key": "<apiKey>",
13	"Content-Type": "application/json"
14	}
15
16	response = requests.post(url, json=payload, headers=headers)
17
18	print(response.json())

1	{
2	"refund_id": "refund_1234567890abcdef"
3	}