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.

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/grosze). 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.

Example Request — partial refund

curl -X POST "https://cart.easy.tools/api/v1/transactions/550e8400-e29b-41d4-a716-446655440000/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/550e8400-e29b-41d4-a716-446655440000/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": "pln"
}

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. "pln")

Error Responses

Bad Request (400)

{
  "message": "Invalid transaction ID"
}

Transaction Not Found (404)

{
  "message": "Transaction with ID <UUID> not found"
}

Validation Error (422)

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 the provider does not support refunds (PayPo has no refund issuer), or when the provider rejects the refund.

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

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

Unauthorized (401)

{
  "message": "Unauthenticated."
}