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

{
  "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)

{
  "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)

{
  "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)

{
  "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

ALTER TABLE orders ADD COLUMN description TEXT;

Transactions Table

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

Constants

Order Status

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

Transaction Status

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

Testing

Run the refund tests:

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

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

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.