# 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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://amplify-docs.gitbook.io/amplify/english/api/refunds.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.