# TELEBIRR Payment Integration Flow

## Overview
Complete payment flow for TELEBIRR integration using the `/payments/initiate` endpoint.

## Payment Flow

### 1. Payment Method Selection
- User selects TELEBIRR from available payment methods
- Payment methods fetched from `/payments/methods`
- Extracts payment method ID for the request

### 2. Payment Initiation
**Endpoint:** `POST /payments/initiate`

**Request:**
```json
{
  "bookingId": "booking-uuid",
  "method": "TELEBIRR",
  "paymentMethodId": "payment-method-uuid",
  "platform": "web"
}
```

**Response:**
```json
{
  "success": true,
  "data": {
    "intentId": "66aa30e2-52a2-4ad0-9043-df6df4a6fa4a",
    "status": "REQUIRES_ACTION",
    "clientAction": {
      "url": "https://sandbox.waafipay.net/v2/hpp/token/2B68686270593243495535774B317263683930574A413D3D",
      "type": "REDIRECT"
    },
    "merchantOrderId": "1781588440170af93c3b9"
  },
  "timestamp": "2026-06-16T05:40:41.004Z"
}
```

### 3. User Redirect
- App stores `intentId` in payment store
- Updates payment status to `REQUIRES_ACTION`
- Redirects user to `clientAction.url`
- User completes payment on WaafiPay gateway

### 4. Callback Handling

#### Success Callback
**URL:** `/booking/payment/telebirr/success`

**Query Parameters:**
- `trxRef` or `outTradeNo` - Transaction reference
- `resultCode` or `code` - Result code
- `resultMsg` or `message` - Result message
- `msisdn` - Phone number (optional)
- `bookingId` - Booking UUID

**Actions:**
1. Logs all query parameters
2. Calls `PATCH /bookings/{bookingId}/confirm` with:
   ```json
   {
     "paymentReference": "trxRef",
     "paymentMethod": "TELEBIRR"
   }
   ```
3. Updates payment status to `SUCCEEDED`
4. Redirects to `/booking/confirmation`

#### Failure Callback
**URL:** `/booking/payment/telebirr/failure`

**Query Parameters:**
- `trxRef` or `outTradeNo` - Transaction reference
- `resultCode` or `code` - Error code
- `resultMsg` or `message` - Error message

**Actions:**
1. Logs all query parameters
2. Updates payment status to `FAILED`
3. Shows error message to user
4. Provides options to retry or go back

## Console Logs

When TELEBIRR payment is initiated, check browser console for:

```
=== TELEBIRR PAYMENT INITIATION ===
Request payload: {
  bookingId: "...",
  method: "TELEBIRR",
  paymentMethodId: "...",
  platform: "web"
}
=== TELEBIRR PAYMENT RESPONSE ===
Full response: {...}
Intent ID: "66aa30e2-52a2-4ad0-9043-df6df4a6fa4a"
Status: "REQUIRES_ACTION"
Client Action: {url: "...", type: "REDIRECT"}
Redirect URL: "https://sandbox.waafipay.net/v2/hpp/token/..."
Merchant Order ID: "1781588440170af93c3b9"
====================================
=== REDIRECTING TO PAYMENT GATEWAY ===
Intent ID: 66aa30e2-52a2-4ad0-9043-df6df4a6fa4a
Status: REQUIRES_ACTION
Merchant Order ID: 1781588440170af93c3b9
Redirect URL: https://sandbox.waafipay.net/v2/hpp/token/...
=======================================
```

## Files Modified

1. **`src/app/booking/payment/page.tsx`**
   - Added TELEBIRR-specific payment initiation
   - Handles redirect response
   - Logs all payment data

2. **`src/lib/payment-store.ts`**
   - Added `REQUIRES_ACTION` status

3. **`src/types/index.ts`**
   - Updated `PaymentMethod` interface

4. **Existing Callback Pages:**
   - `src/app/booking/payment/telebirr/success/page.tsx`
   - `src/app/booking/payment/telebirr/failure/page.tsx`

## Testing Checklist

- [ ] Payment methods load from API
- [ ] TELEBIRR appears in payment options
- [ ] Selecting TELEBIRR calls `/payments/initiate`
- [ ] Console logs show correct request/response
- [ ] User redirects to WaafiPay gateway
- [ ] Success callback confirms booking
- [ ] Failure callback shows error
- [ ] User can retry after failure

## Notes

- Other payment methods still use `/payments/intent` endpoint
- Only TELEBIRR uses the new `/payments/initiate` flow
- Payment store now supports `REQUIRES_ACTION` status
- All callback query parameters are logged for debugging