Issue a Refund

Issue a full or partial refund against a transaction in your store.

The refund is initiated at the payment provider (Stripe or Tpay). Omit amount to refund everything still refundable; pass amount to refund a partial sum.

Refunds are recorded asynchronously

A 202 Accepted means the provider accepted the request. The refund row, its tax split, and the customer notification are written later, when the provider confirms the refund via webhook. As a result, a Get Transaction call made immediately afterwards may not yet show the new entry in refunds or an updated refunded_amount / refund_state.

A refund that the provider has accepted but not completed yet is pending — it already lowers remaining_refundable, but only counts toward refunded_amount once it completes. If it fails, its amount becomes refundable again.

Request

POST /transactions/{id}/refunds

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Transaction UUID

Request Body

Parameter	Type	Required	Description
amount	integer	No	Amount to refund in minor units (e.g. cents). Must be at least 1 and at most the transaction's remaining_refundable. Omit (or send null) to refund the full remaining refundable amount.

Get Transaction exposes remaining_refundable — the maximum amount you can pass here. It is already reduced by any refund that is still pending.

Example Request — partial refund

curl -X POST "https://cart.easy.tools/api/v1/transactions/bf748864-5c90-44d4-b853-ce38820682d7/refunds" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 5000
  }'

Example Request — full refund

curl -X POST "https://cart.easy.tools/api/v1/transactions/bf748864-5c90-44d4-b853-ce38820682d7/refunds" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Response

Success Response (202)

Acknowledges that the refund was submitted to the provider. The amount echoes the amount actually submitted (the full remaining amount when the request omitted amount).

{
  "message": "Refund submitted. It will be recorded once the payment provider confirms it.",
  "amount": 5000,
  "currency": "usd"
}

Response Fields

Field	Type	Nullable	Description
message	string	No	Confirmation that the refund was submitted
amount	integer	No	The amount submitted for refund, in minor units
currency	string	No	Lowercase ISO currency code (e.g. "usd")

Error Responses

Bad Request (400)

{
  "message": "Invalid transaction ID"
}

Not Found Error (404)

{
  "message": "Transaction with ID 2d9f5c8b-4a7e-43b2-8c1f-6e3a9b5d2c74 not found"
}

Validation Error (422 Unprocessable Entity)

Returned when amount is present but not a positive integer.

{
  "message": "The given data was invalid.",
  "errors": {
    "amount": [
      "The amount field must be at least 1."
    ]
  }
}

Refund Cannot Be Issued (422)

Returned when the requested amount exceeds remaining_refundable, when amount is omitted and nothing is left to refund (remaining_refundable is 0), when the payment method does not support refunds (PayPo, for example), or when the refund is rejected. A pending refund counts against remaining_refundable, so a request made while one is pending can return this error even though refunded_amount is below total.

{
  "message": "Refund amount 99999 exceeds the remaining refundable amount 11800"
}

{
  "message": "Refund amount must be at least 1"
}

{
  "message": "Refunds are not supported for this payment provider"
}

Unauthorized Error (401)

{
  "message": "Unauthenticated."
}