edr-platform/apps/edr-passenger-web/portal/PAYMENT_FLOW.md

# TELEBIRR & WAAFI Payment Integration Flow

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

## Payment Flow

### 1. Payment Method Selection
- User selects TELEBIRR or WAAFI 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" | "WAAFI",
  "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 payment gateway

### 4. Callback Handling

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

**Query Parameters:**
- `merchantOrderId` - Merchant order ID (primary reference)
- `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": "merchantOrderId or trxRef",
     "paymentMethod": "TELEBIRR"
   }
   ```
3. Updates payment status to `SUCCEEDED`
4. Redirects to `/booking/confirmation`

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

**Query Parameters:**
- `merchantOrderId` - Merchant order ID
- `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

#### WAAFI Success Callback
**URL:** `/booking/payment/waafi/success`

**Query Parameters:**
- `accountNo` - Account number (e.g., "25377111111")
- `cardNo` - Card number
- `currency` - Currency code (e.g., "DJF")
- `orderId` - Order ID (e.g., "1209631")
- `referenceId` - Reference ID (e.g., "17815888579838ddc23b3")
- `responseCode` - Response code ("0" for success)
- `responseMsg` - Response message (e.g., "Approved (sandbox mode)")
- `state` - Transaction state (e.g., "APPROVED")
- `transactionId` - Transaction ID (e.g., "1318559")
- `txAmount` - Transaction amount (e.g., "367.50")
- `paymentMethod` - Payment method type (e.g., "MWALLET_ACCOUNT")
- `timestamp` - Transaction timestamp
- `bookingId` - Booking UUID

**Example:**
```
?accountNo=25377111111
&cardNo=25377111111
&currency=DJF
&orderId=1209631
&referenceId=17815888579838ddc23b3
&responseCode=0
&responseMsg=Approved+(sandbox+mode)
&state=APPROVED
&transactionId=1318559
&txAmount=367.50
&paymentMethod=MWALLET_ACCOUNT
&timestamp=2026-06-16T08:48:01+03:00
```

**Actions:**
1. Logs all query parameters
2. Calls `PATCH /bookings/{bookingId}/confirm` with:
   ```json
   {
     "paymentReference": "referenceId or transactionId",
     "paymentMethod": "WAAFI",
     "transactionDetails": {
       "transactionId": "1318559",
       "orderId": "1209631",
       "accountNo": "25377111111",
       "amount": "367.50",
       "currency": "DJF",
       "state": "APPROVED",
       "timestamp": "2026-06-16T08:48:01+03:00"
     }
   }
   ```
3. Updates payment status to `SUCCEEDED`
4. Redirects to `/booking/confirmation`

#### WAAFI Failure Callback
**URL:** `/booking/payment/waafi/failure`

**Query Parameters:**
- `referenceId` - Reference ID
- `responseCode` - Error code
- `responseMsg` - Error message
- `orderId` - Order ID
- `transactionId` - Transaction ID
- `state` - Transaction state
- `txAmount` - Transaction amount
- `currency` - Currency code

**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 or WAAFI 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 TELEBIRR 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/...
=======================================
```

## Callback URLs to Share

### TELEBIRR Callback URLs:
- **Success:** `http://localhost:5174/booking/payment/telebirr/success` (dev)
- **Failure:** `http://localhost:5174/booking/payment/telebirr/failure` (dev)
- **Success:** `https://your-domain.com/booking/payment/telebirr/success` (prod)
- **Failure:** `https://your-domain.com/booking/payment/telebirr/failure` (prod)

### WAAFI Callback URLs:
- **Success:** `http://localhost:5174/booking/payment/waafi/success` (dev)
- **Failure:** `http://localhost:5174/booking/payment/waafi/failure` (dev)
- **Success:** `https://your-domain.com/booking/payment/waafi/success` (prod)
- **Failure:** `https://your-domain.com/booking/payment/waafi/failure` (prod)

## Files Modified

1. **`src/app/booking/payment/page.tsx`**
   - Added TELEBIRR and WAAFI 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. **`src/app/booking/payment/telebirr/success/page.tsx`**
   - Handles TELEBIRR success callback with merchantOrderId

5. **`src/app/booking/payment/telebirr/failure/page.tsx`**
   - Handles TELEBIRR failure callback with merchantOrderId

6. **`src/app/booking/payment/waafi/success/page.tsx`**
   - Handles WAAFI success callback with full transaction details

7. **`src/app/booking/payment/waafi/failure/page.tsx`**
   - Handles WAAFI failure callback

## Testing Checklist

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

## Notes

- Only TELEBIRR and WAAFI use `/payments/initiate` endpoint
- Other payment methods use `/payments/intent` endpoint
- Payment store supports `REQUIRES_ACTION` status
- All callback query parameters are logged for debugging
- TELEBIRR uses `merchantOrderId` as primary reference
- WAAFI uses `referenceId` or `transactionId` as primary reference