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:

{
  "bookingId": "booking-uuid",
  "method": "TELEBIRR" | "WAAFI",
  "paymentMethodId": "payment-method-uuid",
  "platform": "web"
}

Response:

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

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

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