# E-Commerce Payments — Frontend Integration

دليل دمج الدفع الإلكتروني في تطبيق العميل. الباك إند بيدير طرق الدفع من
صفحة `website-settings → طرق الدفع`، والتطبيق بيقرأ الطرق المفعّلة
وبيكمّل الدفع بإحدى طريقتين:

- **Web channel (`web`)** — السيرفر بيرجع `payment_url` بيتفتح في
  webview، وبيتحوّل لـ deep link بعد النتيجة. (للبوابات الثلاثة)
- **SDK channel (`sdk`)** — السيرفر بيعمل الـ gateway session
  server-side وبيرجع `session_id` للـ native SDK بتاع البوابة.
  (حالياً Geidea بس)

---

## 1. نظرة عامة على التدفق

### Web channel

```
1) التطبيق يقرأ طرق الدفع المتاحة        → GET  /connector/api/ecommerce/payment-methods
2) العميل يعمل أوردر بطريقة دفع أونلاين   → POST /connector/api/ecommerce/orders
                                            (payment_method = مفتاح البوابة)
3) التطبيق يطلب رابط الدفع للأوردر        → POST /connector/api/ecommerce/orders/{id}/pay
                                            (channel = "web" — الافتراضي)
4) التطبيق يفتح payment_url في webview    → صفحة الدفع عند البوابة (Paymob iframe مثلاً)
5) البوابة ترجع للسيرفر (callback)        → السيرفر يتحقق من HMAC ويحدّث الأوردر
6) السيرفر يحوّل الـ webview              → callback_url?flag=success|fail&token=...
   أو صفحة نجاح/فشل جاهزة (لو مفيش callback_url)
```

### SDK channel (Geidea)

```
1) نفس الخطوتين 1-2 فوق
2) التطبيق يطلب session للأوردر           → POST /connector/api/ecommerce/orders/{id}/pay
                                            (channel = "sdk")
3) السيرفر يعمل Geidea payment-intent     → يرجع { session_id, ... }
4) التطبيق يشغّل الـ native SDK بالـ      → شاشة الدفع native جوه التطبيق
   session_id
5) الـ SDK بيرجع نتيجة للتطبيق           → success / failure / canceled
6) التطبيق يتأكد من السيرفر              → GET /connector/api/ecommerce/payments/{payment_id}/status
```

المبلغ اللي بيتدفع **دايماً** `final_total` بتاع الأوردر من السيرفر —
التطبيق مبيبعتش مبلغ.

---

## 2. الـ Endpoints

| Method | URL | Auth | الوظيفة |
|---|---|---|---|
| GET | `/connector/api/ecommerce/payment-methods?business_id={id}` | public | طرق الدفع المفعّلة للـ checkout |
| POST | `/connector/api/ecommerce/orders` | Bearer | إنشاء الأوردر (موجود أصلاً — فيه `payment_method`) |
| POST | `/connector/api/ecommerce/orders/{id}/pay` | Bearer | محاولة دفع — `channel=web` يرجع `payment_url`، `channel=sdk` يرجع `session_id` |
| GET | `/connector/api/ecommerce/payments/{payment_id}/status` | Bearer | تأكيد نتيجة الدفع بعد الـ SDK (بيسأل البوابة server-side) |
| GET | `/connector/api/ecommerce/orders/{id}` | Bearer | حالة الأوردر — للتحقق من نتيجة الدفع |

كل الـ endpoints تحت `https://{host}/connector/api` والـ authenticated
بياخد `Authorization: Bearer {token}` زي باقي الـ e-commerce APIs.

---

## 3. `GET /connector/api/ecommerce/payment-methods`

بيرجع السويتشات الرئيسية + قائمة البوابات النشطة. لو `digital_payment`
مقفول، القائمة فاضية حتى لو فيه بوابات مفعّلة.

**Query params**

| Param | Required | الوصف |
|---|---|---|
| `business_id` | نعم | الـ business بتاع التطبيق |

**Response**

```json
{
  "success": true,
  "data": {
    "cash_on_delivery": true,
    "digital_payment": true,
    "offline_payment": false,
    "gateways": [
      {
        "gateway": "paymob_accept",
        "gateway_title": "Paymob",
        "gateway_image": "https://{host}/storage/payment_gateways/xxx.png"
      }
    ]
  }
}
```

**قواعد العرض في شاشة الـ checkout:**

- `cash_on_delivery` → اعرض خيار "الدفع عند الاستلام" بقيمة `cash_on_delivery`.
- `digital_payment` + `gateways[]` → اعرض كل بوابة بـ `gateway_title` + `gateway_image`.
- `offline_payment` → طرق يدوية (لسه مش متنفذة — تجاهلها حالياً).

---

## 4. إنشاء الأوردر

`POST /connector/api/ecommerce/orders` — نفس الـ API الموجود. لطريقة دفع
أونلاين ابعت `payment_method` = مفتاح البوابة (`paymob_accept` مثلاً)
بدل `cash_on_delivery`.

```json
{
  "contact_id": 5,
  "payment_method": "paymob_accept",
  "products": [{"product_id": 10, "variation_id": 55, "quantity": 2}]
}
```

الأوردر بيتسجل `payment_status: "unpaid"` و`order_status: "pending"`.

> ملاحظة: لو العميل اختار COD مفيش خطوات تانية — الأوردر خلاص.

---

## 5. `POST /connector/api/ecommerce/orders/{id}/pay`

بيسجّل محاولة دفع على الأوردر وبيرجع الرابط اللي يتفتح في webview.

**Headers**: `Authorization: Bearer {token}`

**Body**

| Field | Required | الوصف |
|---|---|---|
| `gateway` | اختياري | مفتاح البوابة. لو اتبعت بيحدّث `payment_method` بتاع الأوردر؛ لو مش اتبعت بيستخدم القيمة المخزّنة |
| `callback_url` | اختياري لكن **موصى به** | deep link بتاع التطبيق (مثلاً `myapp://payment/result`). للـ web channel بس |
| `channel` | اختياري | `web` (الافتراضي — يرجع `payment_url`) أو `sdk` (يرجع `session_id` — Geidea بس حالياً) |

**Response — web channel**

```json
{
  "success": true,
  "data": {
    "payment_id": 12,
    "payment_url": "https://{host}/ecommerce-payment/paymob/pay?payment_id=12",
    "amount": 250.0,
    "currency": "EGP"
  }
}
```

افتح `payment_url` في webview — هو بيكمّل خطوات البوابة (Paymob: auth →
order → payment key → iframe) وبعدين بيحوّل لصفحة الدفع hosted.

**Response — sdk channel (`channel: "sdk"`, Geidea)**

```json
{
  "success": true,
  "data": {
    "payment_id": 12,
    "session_id": "b4d8a0f2-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "order_id": "abc-xyz",
    "merchant_reference_id": "12",
    "amount": 250.0,
    "currency": "EGP"
  }
}
```

`session_id` ده هو اللي يتحط في `GDPaymentSDKConfiguration(sessionId:)`.
`payment_id` محفوظ لاستخدامه في الـ status endpoint بعد نهاية الـ SDK.

**Response — أخطاء (422)**

| الحالة | `msg` |
|---|---|
| الأوردر مدفوع أو partially paid | `This order is already paid.` |
| البوابة غير مفعّلة / الماستر سويتش مقفول / `payment_method` مش بوابة معروفة | `This payment method is not available.` |
| الأوردر مش بتاع العميل | 404 |

---

## 6. الرجوع من الـ webview

### أ) مع `callback_url` (الطريقة الموصى بها)

بعد الدفع السيرفر بيعمل redirect على:

```
{callback_url}?flag=success|fail&token={base64}
```

`token` بعد فك الـ base64 بيبقى string فيه `key=value` مفصولين بـ `&&`:

```
payment_method=paymob_accept&&order_id=42&&transaction_reference=23456789
```

التطبيق يعمل intercept للـ webview navigation، يقفل الـ webview لما
يلاقي الـ URL بيبدأ بـ `callback_url`، ويقرأ `flag` و`token`.

### ب) بدون `callback_url`

السيرفر بيعرض صفحة جاهزة `payment-success` / `payment-fail` (نجاح/فشل
مع رقم الأوردر). التطبيق يقدر يقفل الـ webview لما يوصل URL فيه
`/ecommerce-payment/success` أو `/ecommerce-payment/fail`.

### التحقق النهائي

**متعتمدش على `flag` لوحده للعرض النهائي** — اعمل `GET orders/{id}` واقرأ:

- `payment_status`: `paid` / `unpaid` / `partial_paid`
- `order_status`: `pending` / `payment_failed` / ...
- `transaction_reference`: مرجع العملية عند البوابة

الـ webhook server-to-server ممكن يوصل بعد الـ redirect بثواني —
لو `flag=success` بس `payment_status` لسه `unpaid`، اعرض "جاري تأكيد
الدفع" واعمل polling لثواني قليلة.

---

## 7. SDK channel — Geidea (Flutter)

لما `channel: "sdk"` السيرفر بيعمل الـ Geidea payment-intent session
لوحده (الـ signature والـ credentials كلها server-side — التطبيق مش
بيشوف أي مفاتيح)، وبيرجعلك `session_id`.

### 7.1 تشغيل الـ SDK

```dart
final response = await _sdk.start(
  configuration: GDPaymentSDKConfiguration(
    sessionId: data['session_id'],        // من الـ pay response
    region: Region.egy,
    language: SDKLanguage.arabic,
  ),
  presentationStyle: const PushStyle(),
);

switch (response.status) {
  case PaymentStatus.success:
    // متحتفلش لسه — لازم تأكد من السيرفر
    await _confirmWithServer(paymentId);
    break;
  case PaymentStatus.failure:
  case PaymentStatus.canceled:
    // اعرض فشل/إلغاء — العميل يقدر يعيد المحاولة
    break;
}
```

> مهم: نتيجة الـ SDK نفسها **مش** التأكيد النهائي. الحالة المؤكدة بتيجي
> من السيرفر اللي بيسأل Geidea مباشرة عن حالة الأوردر.

### 7.2 تأكيد النتيجة — `GET /connector/api/ecommerce/payments/{payment_id}/status`

ينده بعد ما الـ SDK يخلص (ويفضل تعمله polling لثواني لو لسه `is_paid: false`
نتيجة الـ SDK كانت success).

**Headers**: `Authorization: Bearer {token}`

**Response**

```json
{
  "success": true,
  "data": {
    "payment_id": 12,
    "is_paid": true,
    "transaction_id": "abc-xyz",
    "order_id": 42,
    "order_status": "pending",
    "payment_status": "paid"
  }
}
```

- `is_paid: true` → خلاص، اعرض نجاح (`payment_status` على الأوردر بقى `paid`).
- `is_paid: false` بعد `PaymentStatus.success` → اعرض "جاري تأكيد الدفع"
  وعمل retry بعد 2-3 ثواني (البوابة بتحدّث حالة الأوردر بشكل async).
- `is_paid: false` بعد failure/canceled → عرض فشل طبيعي، العميل يقدر يعيد
  `POST orders/{id}/pay` بـ `channel=sdk` لعمل session جديدة.

### 7.3 ملخص الـ SDK flow

```http
POST /connector/api/ecommerce/orders/42/pay
{ "gateway": "geidea", "channel": "sdk" }
# → session_id → شغّل GDPaymentSDK → نتيجة

GET /connector/api/ecommerce/payments/12/status
# → is_paid → اعرض النتيجة النهائية
```

---

## 8. حالات الأوردر المرتبطة بالدفع

| `order_status` | المعنى |
|---|---|
| `pending` | الأوردر لسه مستني (دفع ناجح بيفضل pending لحد ما الأدمن يأكّد) |
| `payment_failed` | الدفع فشل أو اتلغى — العميل يقدر يعيد المحاولة |
| `canceled` | اتلغى |

| `payment_status` | المعنى |
|---|---|
| `unpaid` | لم يُدفع |
| `paid` | اتدفع بالكامل (أونلاين أو يدوي من الأدمن) |
| `partial_paid` | مدفوع جزئياً (يدوي) |

إعادة المحاولة بعد فشل: `POST orders/{id}/pay` تاني — بيعمل محاولة جديدة
ويرجع `payment_url` جديد.

---

## 9. البوابات

| المفتاح (`gateway`) | Web channel | SDK channel | ملاحظات |
|---|---|---|---|
| `paymob_accept` | ✅ Hosted iframe | — | الدفع كله جوه الـ webview |
| `geidea` | ✅ Hosted payment page | ✅ | السيرفر بيتأكد من الحالة بنداء API قبل ما يعلّم paid — في الـ SDK استخدم `payments/{id}/status` |
| `fawry` | ✅ FawryPay redirect | — | التأكيد بييجي من الـ webhook (orderStatus=PAID)؛ لازم `GET orders/{id}` polling بعد الرجوع |

> ملاحظة لـ Fawry: صفحة الرجوع ممكن تظهر قبل ما الـ webhook يوصل —
> لو `flag=fail` بس العميل دفع فعلاً، اعمل polling على `GET orders/{id}`
> لثواني قليلة قبل ما تعرض فشل نهائي.

---

## 9. مثال كامل

```http
# 1) طرق الدفع
GET /connector/api/ecommerce/payment-methods?business_id=1

# 2) الأوردر
POST /connector/api/ecommerce/orders
Authorization: Bearer ...
{
  "contact_id": 5,
  "payment_method": "paymob_accept",
  "products": [{"product_id": 10, "variation_id": 55, "quantity": 1}]
}
# → { "order": { "id": 42, "payment_status": "unpaid", ... } }

# 3a) رابط الدفع — web channel
POST /connector/api/ecommerce/orders/42/pay
{
  "callback_url": "myapp://payment/result"
}
# → { "data": { "payment_url": "https://host/ecommerce-payment/paymob/pay?payment_id=12" } }

# 4) افتح payment_url في webview → العميل يدفع

# 5) الـ webview يوصل:
#    myapp://payment/result?flag=success&token=cGF5bWVudF9tZXRob2Q9...

# 6) تأكيد نهائي
GET /connector/api/ecommerce/orders/42
# → payment_status: "paid", transaction_reference: "..."
```

### مثال — Geidea SDK channel

```http
# 3b) session للـ SDK
POST /connector/api/ecommerce/orders/42/pay
{ "gateway": "geidea", "channel": "sdk" }
# → { "data": { "payment_id": 12, "session_id": "b4d8a0f2-...", ... } }

# 4) شغّل GDPaymentSDK بالـ session_id → العميل يدفع native

# 5) تأكيد النتيجة
GET /connector/api/ecommerce/payments/12/status
# → { "data": { "is_paid": true, "order_status": "pending", ... } }
```

---

## 11. ملاحظات للاختبار

- البوابة ليها `mode`: `test` أو `live` — الأدمن بيحدده من صفحة الإعدادات.
  في test استخدم كروت Paymob التجريبية.
- الـ callback محمي بـ HMAC — طلبات مزوّرة بدون توقيع صحيح بتترفض.
- كل محاولة دفع بتتسجل في `ecommerce_payment_requests` — السيرفر بيسمح
  بأكتر من محاولة لنفس الأوردر، وأي callback ناجح بيحدّث الأوردر مرة واحدة.
