# Refunds

This API provides endpoints for managing refunds related to payments. It includes the ability to create, retrieve, and list refunds.

## 1. List refunds

\[GET] /refunds

This endpoint retrieves a list of refunds based on query parameters. It supports filtering, pagination, and sorting.

Request:

```
const query = {
  page: number,  // Page number for pagination
  limit: number, // Number of items per page
  query: object  // Optional filter conditions
};
```

**Query Parameters:**

* `page`: The page number for pagination (optional, defaults to 1).
* `limit`: The number of refunds to retrieve per page (optional, defaults to 10).
* `query`: A comma-separated list of key-value pairs to filter results. The keys will be the refund fields, and values will be used to match corresponding fields (optional).

**Response:**

```
{
  "refunds": [ /* Array of refund objects */ ],
  "page": 1,
  "pageSize": 10,
  "totalPages": 5
}
```

Refund Object Example:

```
{
  "_id": "string",
  "paymentIntentId": "string",
  "paymentId": "string",
  "userId": "string",
  "receiverId": "string",
  "refundTo": "string",
  "amount": 100,
  "status": "PROCESSING",
  "createdAt": "timestamp",
  "updatedAt": "timestamp"
}
```

## 2. Get Refund by ID

\[GET] /refunds/:id

This endpoint retrieves a specific refund by its ID.

**Request:**

* **URL Parameter:**
  * `id`: The ID of the refund to retrieve.

**Response:**

```
{
  "_id": "string",
  "paymentIntentId": "string",
  "paymentId": "string",
  "userId": "string",
  "receiverId": "string",
  "refundTo": "string",
  "amount": 100,
  "status": "PROCESSING",
  "createdAt": "timestamp",
  "updatedAt": "timestamp"
}
```

## 3. Create Refund

\[POST] /refunds

This endpoint creates a new refund for an existing payment.

Request:

```
{
  "paymentId": "string",// The ID of the payment to refund
  "refundTo": "string"// The address to send the refund to (must be a valid address)
}
```

Response:

```
{
  "_id": "string",
  "paymentIntentId": "string",
  "paymentId": "string",
  "userId": "string",
  "receiverId": "string",
  "refundTo": "string",
  "amount": 100,
  "status": "PROCESSING",
  "createdAt": "timestamp",
  "updatedAt": "timestamp"
}
```

**Validation:**

* The request must include a valid `paymentId` and `refundTo` address.
* The `paymentId` must correspond to a confirmed payment.
* The `refundTo` address must be a valid Ethereum address (starts with "0x" and has a length of 42 characters).
* The refund amount must not exceed the available funds in the receiver’s account.
* Refunds cannot be processed if the payment has been withdrawn.

**Error Responses:**

* **400 Bad Request**: Missing required fields or invalid data (e.g., invalid address, insufficient funds).
* **401 Unauthorized**: If the user is not authenticated.
* **404 Not Found**: If the payment or refund does not exist.
* **500 Internal Server Error**: If an unexpected error occurs.
* **500 Internal Server Error**: If an unexpected error occurs.

## 4.  Create Partial Refunds

\[POST] /refunds/partial

This endpoint creates a new partial refund for an existing payment.

Request:

```
{
  "paymentId": "string",// The ID of the payment to refund
  "refundTo": "string",// The address to send the refund to (must be a valid address)
  "amount": "number" // The amount to be refunded
}
```

Response:

```
{
  "_id": "string",
  "paymentIntentId": "string",
  "paymentId": "string",
  "userId": "string",
  "receiverId": "string",
  "refundTo": "string",
  "amount": 100,
  "status": "PROCESSING",
  "createdAt": "timestamp",
  "updatedAt": "timestamp"
}

```

**Validation:**

* The request must include a valid `paymentId` and `refundTo` address.
* The `paymentId` must correspond to a confirmed payment.
* The `refundTo` address must be a valid Ethereum address (starts with "0x" and has a length of 42 characters).
* The refund amount must not exceed the available funds in the receiver’s account.
* Refunds cannot be processed if the payment has been withdrawn.

**Error Responses:**

* **400 Bad Request**: Missing required fields or invalid data (e.g., invalid address, insufficient funds).
* **401 Unauthorized**: If the user is not authenticated.
* **404 Not Found**: If the payment or refund does not exist.
* **500 Internal Server Error**: If an unexpected error occurs.
* **500 Internal Server Error**: If an unexpected error occurs.