# 🛒 Checkout Summary API Examples

## Overview

The `/api/payments/checkout-summary` endpoint provides a comprehensive transaction summary before payment initiation. It calculates pricing, applies discounts, validates coupons, and shows what the customer will receive.

**Important Note:** All checkout summaries include a platform admin fee of Rp 4,000 ("Biaya Admin Platform Pembayaran") which is automatically added to the final amount.

## API Endpoint

**POST** `/api/payments/checkout-summary`

**Headers:**
```
Authorization: Bearer {token}
Content-Type: application/json
Accept: application/json
```

## Request Examples

### 1. Basic Package Checkout (No Coupon)

**Request:**
```json
{
  "package_id": 1
}
```

**Response:**
```json
{
  "success": true,
  "message": "Checkout summary generated successfully.",
  "data": {
    "checkout_id": "PREVIEW-ABC12345-123",
    "package": {
      "id": 1,
      "name": "Ksatria PCPM",
      "slug": "ksatria-pcpm",
      "description": "Complete PCPM preparation package",
      "duration_months": 12,
      "features": ["Unlimited Quiz Access", "Live Classes", "Flashcards"],
      "category_access": ["all"],
      "badge_text": "Most Popular"
    },
    "pricing": {
      "original_price": 500000,
      "current_price": 400000,
      "subtotal": 400000,
      "package_final_amount": 400000,
      "platform_admin_fee": 4000,
      "final_amount": 404000,
      "currency": "IDR"
    },
    "discounts": {
      "package_discount": {
        "has_discount": true,
        "amount": 100000,
        "percentage": 20
      },
      "coupon_discount": {
        "applied": false,
        "amount": 0,
        "percentage": 0,
        "coupon": null,
        "error": null
      },
      "total_discount": 100000,
      "total_savings": 100000,
      "total_savings_percentage": 20
    },
    "payment_info": {
      "can_proceed": true,
      "minimum_amount": 1000
    },
    "summary": {
      "items": [
        {
          "name": "Ksatria PCPM Package",
          "quantity": 1,
          "unit_price": 400000,
          "total_price": 400000
        },
        {
          "name": "Biaya Admin Platform Pembayaran",
          "quantity": 1,
          "unit_price": 4000,
          "total_price": 4000
        }
      ],
      "subtotal": 400000,
      "total_discount": 100000,
      "package_final_amount": 400000,
      "platform_admin_fee": 4000,
      "final_amount": 404000,
      "savings_message": "You save Rp 100.000 (20%) with this purchase!"
    }
  }
}
```

### 2. Package with Valid Coupon

**Request:**
```json
{
  "package_id": 1,
  "coupon_code": "WELCOME10"
}
```

**Response:**
```json
{
  "success": true,
  "data": {
    "pricing": {
      "original_price": 500000,
      "current_price": 400000,
      "subtotal": 400000,
      "package_final_amount": 360000,
      "platform_admin_fee": 4000,
      "final_amount": 364000,
      "currency": "IDR"
    },
    "discounts": {
      "package_discount": {
        "has_discount": true,
        "amount": 100000,
        "percentage": 20
      },
      "coupon_discount": {
        "applied": true,
        "amount": 40000,
        "percentage": 10,
        "coupon": {
          "id": 1,
          "code": "WELCOME10",
          "name": "Welcome Discount 10%",
          "discount_type": "percentage",
          "discount_value": 10,
          "remaining_usage": 99,
          "customer_remaining_usage": 1
        },
        "error": null
      },
      "total_discount": 140000,
      "total_savings": 140000,
      "total_savings_percentage": 28
    },
    "payment_info": {
      "can_proceed": true
    },
    "summary": {
      "items": [
        {
          "name": "Ksatria PCPM Package",
          "quantity": 1,
          "unit_price": 400000,
          "total_price": 400000
        },
        {
          "name": "Biaya Admin Platform Pembayaran",
          "quantity": 1,
          "unit_price": 4000,
          "total_price": 4000
        }
      ],
      "subtotal": 400000,
      "total_discount": 140000,
      "package_final_amount": 360000,
      "platform_admin_fee": 4000,
      "final_amount": 364000,
      "savings_message": "You save Rp 140.000 (28%) with this purchase!"
    }
  }
}
```

### 3. Invalid Coupon Code

**Request:**
```json
{
  "package_id": 1,
  "coupon_code": "INVALID123"
}
```

**Response:**
```json
{
  "success": true,
  "data": {
    "pricing": {
      "original_price": 500000,
      "current_price": 400000,
      "subtotal": 400000,
      "package_final_amount": 400000,
      "platform_admin_fee": 4000,
      "final_amount": 404000,
      "currency": "IDR"
    },
    "discounts": {
      "coupon_discount": {
        "applied": false,
        "amount": 0,
        "percentage": 0,
        "coupon": null,
        "error": {
          "code": "COUPON_NOT_FOUND",
          "message": "Coupon code not found."
        }
      }
    },
    "payment_info": {
      "can_proceed": true
    }
  }
}
```

### 4. Expired Coupon

**Request:**
```json
{
  "package_id": 1,
  "coupon_code": "EXPIRED"
}
```

**Response:**
```json
{
  "success": true,
  "data": {
    "discounts": {
      "coupon_discount": {
        "applied": false,
        "error": {
          "code": "COUPON_EXPIRED",
          "message": "Coupon has expired."
        }
      }
    },
    "payment_info": {
      "can_proceed": true
    }
  }
}
```

### 5. Customer Already Has Package

**Request:**
```json
{
  "package_id": 1
}
```

**Response:**
```json
{
  "success": false,
  "message": "You already have an active subscription to this package",
  "error_code": "ALREADY_SUBSCRIBED"
}
```

### 6. Inactive Package

**Request:**
```json
{
  "package_id": 999
}
```

**Response:**
```json
{
  "success": false,
  "message": "This package is no longer available for purchase",
  "error_code": "PACKAGE_INACTIVE"
}
```

## Error Codes

| Error Code | Description |
|------------|-------------|
| `PACKAGE_INACTIVE` | Package is not active or available |
| `ALREADY_SUBSCRIBED` | Customer already has active subscription |
| `COUPON_NOT_FOUND` | Coupon code doesn't exist |
| `COUPON_EXPIRED` | Coupon has passed expiration date |
| `COUPON_INACTIVE` | Coupon is disabled |
| `COUPON_USAGE_LIMIT_REACHED` | Coupon has reached its usage limit |
| `CUSTOMER_USAGE_LIMIT_REACHED` | Customer has used coupon max times |
| `NO_DISCOUNT_APPLICABLE` | Coupon provides no discount for amount |

## Use Cases

### 1. Shopping Cart Summary
Display comprehensive pricing breakdown before payment:
- Original vs discounted pricing
- Applied coupon details
- Total savings calculation
- Package access details

### 2. Coupon Validation
Real-time coupon validation and discount calculation:
- Validate coupon codes as user types
- Show discount amounts immediately
- Handle various error scenarios gracefully

### 3. Payment Preparation
Gather all information needed for payment initiation:
- Final amount to charge
- Package and customer details
- Discount breakdown for transaction records

### 4. Price Comparison
Allow customers to:
- Compare different packages
- Test various coupon codes
- See maximum possible savings

## Integration Flow

```
1. Customer selects package
2. Optional: Customer enters coupon code
3. Call /checkout-summary endpoint
4. Display pricing breakdown to customer
5. Customer confirms purchase
6. Call /payments/initiate endpoint
7. Process payment via Midtrans
```

## Notes

- The checkout summary does NOT create any transactions
- It's safe to call multiple times for price calculations
- Coupon validation happens in real-time
- All pricing calculations include package discounts and coupon discounts
- The `checkout_id` is for reference only (not used in actual payment)