External Integrations

HyperPay, STC Pay, MADA, Apple Pay, Maps, SMS, Email, Push Notifications

1. Purpose

This document defines all external integrations explicitly present in the system UI and analysis:

Payment Gateways

HyperPay (Primary Processor)
MADA (via HyperPay)
Apple Pay (via HyperPay)
STC Pay
SADAD (as seen in UI)

Maps Integration

Google Maps (Links only — no embedded map features)

Messaging

SMS Provider (brand not specified → generic integration)
Email Provider (brand not specified → generic integration)

Push Notifications

Firebase Cloud Messaging (Mobile Apps only)

❗ No integration not mentioned in the UI/flows will be invented.

2. Payment Integrations – High-Level Architecture

The payment flow is unified across:

Booking Payments (B2C Web / B2C Mobile)
Ad Campaign Payments (B2B Provider Portal)
Future expansions via same payment layer

PaymentService → GatewayDriver (HyperPay / STCPay / SADAD) → PaymentTransaction record → Callback handling → Status updates → Financial ledger + Reports

3. HyperPay Integration

HyperPay is the primary payment processor.

Supported methods based on UI:

Method	Visible in UI	Processed via HyperPay
Credit Card	✔️	✔️
Debit Card (MADA)	✔️	✔️
Apple Pay	✔️	✔️
Visa / MasterCard	✔️	✔️

3.1 Initiating Payment Session

POST/api/v1/payments/session

3.2 Callback

POST/api/v1/payments/callback/hyperpay

Backend responsibilities:

Validate signature
Match booking_id or campaign_id
Create/Update payment_transactions record
Update booking_status or ad_campaign_status
Trigger financial logs

3.3 Supported Status Codes Mapping

HyperPay Code	Internal Status
000.000.000	SUCCESS
000.100.100	PENDING
800.400.xxx	DECLINED
999.999.999	ERROR

4. STC Pay Integration

Shown in UI under B2C booking and Ad Campaign payment methods.

Process flow:

Backend calls STC Pay to create payment request
STC Pay provides a QR or deeplink
User pays from STC Pay app
Callback hits backend

4.1 Init Session

POST/api/v1/payments/stcpay/session

POST/api/v1/payments/callback/stcpay

Callback

5. SADAD Integration

Visible in UI (Payment Options). Assumed similar to STC Pay flow but requires SADAD number assignment and callback validation.

POST/api/v1/payments/sadad/session

6. Apple Pay Integration (via HyperPay)

UI shows Apple Pay icon in Web & Mobile booking/payment.

Only supported on iOS / Safari environments
Implemented through HyperPay → tokenized card

7. MADA Integration (via HyperPay)

UI shows MADA icon. No special API required; HyperPay identifies MADA BIN ranges.

8. Google Maps Integration

UI only shows: "انسخ رابط الموقع", displaying a location pin icon in lists, and address text. No interactive map inside UI.

Maps integration is link-based only.

Fields:

location_url (string) — Stored and rendered as anchor

Not used:

Google Maps API keys
Embedded JS Maps
Reverse geocoding

9. SMS Provider Integration

Used for: OTP (if implemented), Notifications to customers, Urgent alerts.

Since no brand is mentioned, integration must be generic via SmsService → SmsProviderDriver.

POST/api/v1/notifications/sms/send

10. Email Provider Integration

Used for: Booking confirmation, Payment receipts, Support messages, Marketing emails (optional).

POST/api/v1/notifications/email/send

11. Firebase Push Notifications

Enabled in Mobile Apps (Flutter). Used for:

Booking updates
Payment success/failure
Trip starting reminders
Ad campaign status notifications (Provider Portal Mobile)

POST/api/v1/notifications/push/send

12. Security Notes

12.1 Secure Fields (Never logged)

Card numbers
CVV
Apple Pay tokens
STC Pay transaction secrets

12.2 Signed Callbacks

HyperPay, STC Pay, and SADAD callbacks must validate: Signature, Hash, Transaction ID mapping

12.3 Replay Protection

Use nonce / timestamp validation.

13. Error Handling

Unified error format applies:

{
  "error": "PAYMENT_FAILED",
  "details": {
    "gateway": "HYPERPAY",
    "code": "800.400.100",
    "message": "Card declined"
  }
}

14. Testing Guidelines

Use test cards provided by HyperPay
STC Pay sandbox via simulated endpoints
No live callbacks tested in staging
Webhooks logged to payment_webhook_logs table

15. Open Questions

VAT inconsistency (15% vs 20%) — requires business validation
SADAD availability — real or placeholder?
SMS provider choice not specified
Email provider choice not specified
Will Maps become interactive in future (Google Maps SDK)?