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

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:

{
  "bookingId": "booking-uuid",
  "method": "TELEBIRR",
  "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 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:

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