> ## Documentation Index
> Fetch the complete documentation index at: https://docs.peere.co/llms.txt
> Use this file to discover all available pages before exploring further.

# schemas

# Refund Management Schemas

API endpoints for processing refunds and handling payment reversals.

## Endpoints

| Method | Endpoint                       | Description                     |
| ------ | ------------------------------ | ------------------------------- |
| POST   | `/v1/refunds/initiate`         | Initiate refund for transaction |
| GET    | `/v1/refunds/:refundId/status` | Get refund status               |

## POST /v1/refunds/initiate

Initiate a refund for a completed transaction.

### Request Body

```json theme={null}
{
  "transactionId": "string",
  "amount": 25.0,
  "reason": "string",
  "refundType": "full | partial",
  "metadata": {}
}
```

### Request Schema

| Field           | Type   | Required | Description                      |
| --------------- | ------ | -------- | -------------------------------- |
| `transactionId` | string | Yes      | Original transaction ID          |
| `amount`        | number | Yes      | Refund amount                    |
| `reason`        | string | Yes      | Reason for refund                |
| `refundType`    | string | Yes      | Type of refund (full or partial) |
| `metadata`      | object | No       | Additional metadata              |

### Response Schema

```json theme={null}
{
  "statusCode": 201,
  "success": true,
  "message": "Refund initiated successfully",
  "data": {
    "refundId": "string",
    "status": "pending | processing | completed",
    "estimatedProcessingTime": "string"
  }
}
```

### Response Fields

| Field                     | Type   | Description               |
| ------------------------- | ------ | ------------------------- |
| `refundId`                | string | Unique refund identifier  |
| `status`                  | string | Current refund status     |
| `estimatedProcessingTime` | string | Estimated processing time |

## GET /v1/refunds/:refundId/status

Get the current status and details of a refund.

### Path Parameters

| Parameter  | Type   | Required | Description       |
| ---------- | ------ | -------- | ----------------- |
| `refundId` | string | Yes      | Refund identifier |

### Response Schema

```json theme={null}
{
  "statusCode": 200,
  "success": true,
  "message": "Refund status retrieved successfully",
  "refund": {
    "refundId": "string",
    "originalTransactionId": "string",
    "amount": 25.0,
    "originalAmount": 50.0,
    "currency": "string",
    "status": "pending | processing | completed | failed",
    "refundType": "full | partial",
    "reason": "string",
    "initiatedBy": "string",
    "processedAt": "string",
    "createdAt": "string",
    "updatedAt": "string"
  }
}
```

## Refund Schema

| Field                   | Type   | Description                 |
| ----------------------- | ------ | --------------------------- |
| `refundId`              | string | Unique refund identifier    |
| `originalTransactionId` | string | Original transaction ID     |
| `amount`                | number | Refund amount               |
| `originalAmount`        | number | Original transaction amount |
| `currency`              | string | Currency code               |
| `status`                | string | Refund status               |
| `refundType`            | string | Type of refund              |
| `reason`                | string | Refund reason               |
| `initiatedBy`           | string | Who initiated the refund    |
| `processedAt`           | string | Processing timestamp        |
| `createdAt`             | string | Creation timestamp          |
| `updatedAt`             | string | Last update timestamp       |

## Refund Status Types

| Status       | Description                           |
| ------------ | ------------------------------------- |
| `pending`    | Refund initiated, awaiting processing |
| `processing` | Refund is being processed by bank     |
| `completed`  | Refund successfully processed         |
| `failed`     | Refund failed or was rejected         |
| `cancelled`  | Refund was cancelled                  |

## Refund Types

| Type      | Description                           |
| --------- | ------------------------------------- |
| `full`    | Complete refund of transaction amount |
| `partial` | Partial refund of transaction amount  |

## Error Responses

### 400 Bad Request

```json theme={null}
{
  "statusCode": 400,
  "success": false,
  "message": "Refund amount cannot exceed original transaction amount"
}
```

### 404 Not Found

```json theme={null}
{
  "statusCode": 404,
  "success": false,
  "message": "Original transaction not found"
}
```

### 409 Conflict

```json theme={null}
{
  "statusCode": 409,
  "success": false,
  "message": "Transaction has already been fully refunded"
}
```