# Refunds

The SimPay system allows for easy and automated refunding of funds to customers (e.g., in case of withdrawal from a contract, complaint, or order cancellation). You can initiate this process directly from our API, without the need to manually order bank transfers from the Billing Panel.

## Formal and Technical Requirements

Before initiating a refund, make sure the given transaction meets all of the following conditions. If any of them are not met, the API will return an error.

* **Transaction status:** The transaction must be fully paid (have the `transaction_paid` status).
* **Available balance:** Your account (SimPay balance) must have sufficient funds to cover the refund being ordered.
* **Maximum amount:** The sum of all previous refunds for a given transaction cannot exceed its original value.
* **Transaction age:** A refund can only be ordered for transactions that are no older than **30 days**.
* **No tests:** Refunds can only be made for real (production) transactions. You cannot order a refund for a test transaction.
* **No duplicates:** At any given time, a transaction cannot have another pending refund order (status `refund_new` or `refund_pending`). You must wait for the previous order to finish processing.


## Full and Partial Refunds

Depending on your needs, SimPay allows two types of refunds:

1. **Partial refund** – you return only part of the amount to the customer (e.g., when they return only one of several ordered products). To perform it, pass the `amount` parameter with the appropriate amount in the request body.
2. **Full refund (100%)** – you return the entire paid amount. You have two options here: you can omit the `amount` parameter in the request (the system will then refund the full transaction value by default) or explicitly provide the original order amount.


## Creating a Refund (API Examples)

To generate a refund, send a `POST` request to the endpoint:
`/payment/{serviceId}/transactions/{transactionId}/refunds`

### Example: Partial Refund (e.g., for 25.50 PLN)


```bash
curl -X POST "https://api.simpay.pl/payment/{serviceId}/transactions/{transactionId}/refunds" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "amount": "25.50"
  }'
```

### Example: Full Refund (omitting the amount parameter)


```bash
curl -X POST "https://api.simpay.pl/payment/{serviceId}/transactions/{transactionId}/refunds" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{}'
```

### API Response and `refundId` Identifier

After sending a valid request, the operation will be queued and will receive an initial status of `refund_new`. In the response from our API, you will receive an object containing a unique identifier for this order – **`refundId`**.

> **Important:** Remember to save the `refundId` value in your database alongside the transaction identifier! It will be essential for correctly matching and handling future IPN notifications (webhooks) with status changes for this specific refund.


## Refund Lifecycle

Ordering a refund does not mean that the money will immediately appear in the customer's account. This process is subject to specific stages and system statuses.

👉 **[Go to: Refund Statuses](/payment/statuses#statusGroup=Refund+Statuses)**, to check the full lifecycle, transition diagrams, and instructions on how we notify your application about the successful completion of a refund operation.