apskel-pos-backend/docs/REFUND_API.md

# Refund Order API Documentation

## Overview

The Refund Order API provides comprehensive functionality to process refunds for paid orders. This includes order status updates, transaction creation, customer voucher reversal, payment gateway refunds, and customer notifications.

## Features

- ✅ **Order Status Management**: Updates order status to "REFUNDED"
- ✅ **Transaction Tracking**: Creates refund transactions with negative amounts
- ✅ **Customer Voucher Reversal**: Reverses any vouchers/points given for the order
- ✅ **Payment Gateway Integration**: Handles refunds for non-cash payments
- ✅ **Customer Notifications**: Sends email notifications for refunds
- ✅ **Audit Trail**: Tracks who processed the refund and when
- ✅ **Refund History**: Provides endpoint to view refund history

## API Endpoints

### 1. Process Refund

**POST** `/order/refund`

Process a refund for a paid order.

#### Request Body

```json
{
  "order_id": 123,
  "reason": "Customer request"
}
```

#### Request Parameters

| Parameter | Type   | Required | Description                    |
|-----------|--------|----------|--------------------------------|
| order_id  | int64  | Yes      | ID of the order to refund      |
| reason    | string | Yes      | Reason for the refund          |

#### Response

**Success (200 OK)**

```json
{
  "success": true,
  "status": 200,
  "data": {
    "order_id": 123,
    "status": "REFUNDED",
    "refund_amount": 100000,
    "reason": "Customer request",
    "refunded_at": "2024-01-15T10:30:00Z",
    "customer_name": "John Doe",
    "payment_type": "CASH"
  }
}
```

**Error (400 Bad Request)**

```json
{
  "success": false,
  "status": 400,
  "message": "only paid order can be refund"
}
```

### 2. Get Refund History

**GET** `/order/refund-history`

Retrieve refund history with filtering and pagination.

#### Query Parameters

| Parameter   | Type   | Required | Description                    |
|-------------|--------|----------|--------------------------------|
| limit       | int    | No       | Number of records (max 100)    |
| offset      | int    | No       | Number of records to skip      |
| start_date  | string | No       | Start date (RFC3339 format)    |
| end_date    | string | No       | End date (RFC3339 format)      |

#### Response

**Success (200 OK)**

```json
{
  "success": true,
  "status": 200,
  "data": [
    {
      "order_id": 123,
      "customer_name": "John Doe",
      "customer_id": 456,
      "is_member": true,
      "status": "REFUNDED",
      "amount": 95000,
      "total": 100000,
      "payment_type": "CASH",
      "table_number": "A1",
      "order_type": "DINE_IN",
      "created_at": "2024-01-15T09:00:00Z",
      "refunded_at": "2024-01-15T10:30:00Z",
      "tax": 5000
    }
  ],
  "paging_meta": {
    "page": 1,
    "total": 25,
    "limit": 20
  }
}
```

## Business Logic

### Refund Process Flow

1. **Validation**
   - Verify order exists and belongs to partner
   - Ensure order status is "PAID"
   - Validate refund reason

2. **Order Update**
   - Update order status to "REFUNDED"
   - Store refund reason in order description
   - Update timestamp

3. **Transaction Creation**
   - Create refund transaction with negative amount
   - Set transaction type to "REFUND"
   - Track who processed the refund

4. **Customer Voucher Reversal**
   - Find vouchers associated with the order
   - Mark vouchers as reversed/cancelled
   - Adjust customer points if applicable

5. **Payment Gateway Refund**
   - For non-cash payments, call payment gateway refund API
   - Handle gateway response and errors
   - Update transaction with gateway details

6. **Customer Notification**
   - Send email notification to customer
   - Include refund details and reason
   - Provide transaction reference

### Supported Payment Methods

| Payment Method | Refund Handling                    |
|----------------|-----------------------------------|
| CASH           | Manual refund (no gateway call)   |
| QRIS           | Gateway refund via provider API   |
| CARD           | Gateway refund via provider API   |
| TRANSFER       | Gateway refund via provider API   |
| ONLINE         | Gateway refund via provider API   |

### Error Handling

- **Order not found**: Returns 404 error
- **Order not paid**: Returns 400 error with message
- **Voucher reversal failure**: Logs warning but continues refund
- **Payment gateway failure**: Logs error but continues refund
- **Notification failure**: Logs warning but continues refund

## Database Schema

### Orders Table

```sql
ALTER TABLE orders ADD COLUMN description TEXT;
```

### Transactions Table

```sql
-- Refund transactions have negative amounts
-- Transaction type: "REFUND"
-- Status: "REFUND"
```

## Constants

### Order Status

```go
const (
    New      OrderStatus = "NEW"
    Paid     OrderStatus = "PAID"
    Cancel   OrderStatus = "CANCEL"
    Pending  OrderStatus = "PENDING"
    Refunded OrderStatus = "REFUNDED"  // New status
)
```

### Transaction Status

```go
const (
    New     PaymentStatus = "NEW"
    Paid    PaymentStatus = "PAID"
    Cancel  PaymentStatus = "CANCEL"
    Refund  PaymentStatus = "REFUND"   // New status
)
```

## Testing

Run the refund tests:

```bash
go test ./internal/services/v2/order -v -run TestRefund
```

## Security Considerations

1. **Authorization**: Only authorized users can process refunds
2. **Audit Trail**: All refunds are logged with user and timestamp
3. **Validation**: Strict validation prevents invalid refunds
4. **Rate Limiting**: Consider implementing rate limiting for refund endpoints

## Future Enhancements

1. **Partial Refunds**: Support for refunding specific order items
2. **Refund Approval Workflow**: Multi-level approval for large refunds
3. **Refund Analytics**: Dashboard for refund trends and analysis
4. **Automated Refunds**: Integration with customer service systems
5. **Refund Templates**: Predefined refund reasons and templates

## Integration Examples

### cURL Example

```bash
curl -X POST http://localhost:8080/api/v1/order/refund \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -d '{
    "order_id": 123,
    "reason": "Customer request"
  }'
```

### JavaScript Example

```javascript
const refundOrder = async (orderId, reason) => {
  const response = await fetch('/api/v1/order/refund', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${token}`
    },
    body: JSON.stringify({
      order_id: orderId,
      reason: reason
    })
  });
  
  return response.json();
};
```

## Support

For questions or issues with the refund API, please contact the development team or create an issue in the project repository.