# MyFatoorah Payment Flow

## Overview

The payment system uses MyFatoorah as the payment gateway. The mobile app selects a payment method ID from the available methods list, and the backend initiates the payment with MyFatoorah and returns a `payment_url` for the user to complete the payment.

---

## Step 1 — Get Available Payment Methods

**Endpoint:**
```
GET /api/general/payments/myfatoorah/payment-methods
```

**Headers:**
| Header | Value |
|--------|-------|
| `Agent-Token` | `any-string` |
| `Accept` | `application/json` |

**No auth token required.**

**Response:**
```json
{
    "status": "success",
    "message": "Payment methods retrieved successfully",
    "data": [
        {
            "payment_method_id": 6,
            "payment_method_en": "MADA",
            "payment_method_ar": "مدى",
            "payment_method_code": "md",
            "is_direct": false,
            "service_charge": 12.361,
            "total_amount": 1,
            "currency_iso": "SAR",
            "image_url": "https://demo.myfatoorah.com/imgs/payment-methods/md.png"
        },
        {
            "payment_method_id": 2,
            "payment_method_en": "VISA/MASTER",
            "payment_method_ar": "فيزا / ماستر",
            "payment_method_code": "vm",
            "is_direct": false,
            "service_charge": 1.237,
            "total_amount": 1,
            "currency_iso": "SAR",
            "image_url": "https://demo.myfatoorah.com/imgs/payment-methods/vm.png"
        },
        {
            "payment_method_id": 11,
            "payment_method_en": "Apple Pay",
            "payment_method_ar": "أبل باي",
            "payment_method_code": "ap",
            "is_direct": false,
            "service_charge": 0,
            "total_amount": 1,
            "currency_iso": "SAR",
            "image_url": "https://demo.myfatoorah.com/imgs/payment-methods/ap.png"
        }
    ]
}
```

---

## Step 2 — Create Order with Payment Method

**Endpoint:**
```
POST /api/app/client/orders
```

**Headers:**
| Header | Value |
|--------|-------|
| `Agent-Token` | `any-string` |
| `Accept` | `application/json` |
| `Authorization` | `Bearer {token}` |

**Body:**
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `location_id` | integer | ✅ | Client delivery location ID |
| `delivery_method` | string | ✅ | `delivery` or `receive` |
| `vendor_payments[{vendor_id}]` | string | ✅ | `online`, `wallet`, `cod`, `deferred` |
| `payment_method_id` | integer | ❌ | MyFatoorah payment method ID from Step 1 |
| `coupon_code` | string | ❌ | Coupon code |
| `distance` | float | ❌ | Distance in km |

**Example — Pay with MADA:**
```
location_id          = 76
delivery_method      = delivery
vendor_payments[2]   = online
payment_method_id    = 6
```

**Example — Pay with Visa/Master:**
```
location_id          = 76
delivery_method      = delivery
vendor_payments[2]   = online
payment_method_id    = 2
```

**Example — Pay with Apple Pay:**
```
location_id          = 76
delivery_method      = delivery
vendor_payments[2]   = online
payment_method_id    = 11
```

**Example — Pay with Wallet (no payment_method_id needed):**
```
location_id          = 76
delivery_method      = delivery
vendor_payments[2]   = wallet
```

> If `payment_method_id` is not provided, the default from server config is used (`VISA/MASTER`).

---

## Step 3 — Handle Response

### Case A: Gateway payment required (online)
```json
{
    "status": "success",
    "message": "Payment initiated successfully",
    "data": {
        "status": "pending_payment",
        "session_id": 125,
        "reference": "CHK-XXXXXXXXXXXXXX",
        "invoice_id": 97387883,
        "payment_url": "https://sa.myfatoorah.com/En/SAU/PayInvoice/Checkout?invoiceKey=...",
        "amount": 10.79,
        "currency": "SAR"
    }
}
```

→ Mobile app opens `payment_url` in a **WebView** or browser.
→ User completes payment on MyFatoorah's hosted page.
→ MyFatoorah calls the backend callback and the order is created automatically.

### Case B: No gateway needed (wallet / free order)
```json
{
    "status": "success",
    "message": "order created successfully",
    "data": null
}
```

→ Order is created immediately, no redirect needed.

---

## Step 4 — Payment Callback (handled by backend)

MyFatoorah calls the backend automatically after payment:

```
GET/POST /api/general/payments/myfatoorah/callback?reference=CHK-XXXX
```

The backend:
1. Verifies payment status with MyFatoorah
2. Creates the order
3. Marks the checkout session as completed

The mobile app can poll or use the `reference` to check order status.

---

## Payment Methods Reference

| ID | Name | Code |
|----|------|------|
| 2 | VISA/MASTER | vm |
| 6 | MADA | md |
| 11 | Apple Pay | ap |
| 14 | STC Pay | stc |
| 32 | Google Pay | gp |
| 3 | AMEX | ae |
| 1 | KNET | kn |
| 5 | Benefit | b |

---

## Notes

- Apple Pay (`payment_method_id = 11`) works as a **hosted redirect** — MyFatoorah opens their Apple Pay page. Native Apple Pay (using `InitiateSession`) requires additional certificate setup with MyFatoorah.
- `vendor_payments` map uses your internal payment type (`online`, `wallet`, `deferred`, `cod`) — not the MyFatoorah method ID.
- `payment_method_id` only applies when `vendor_payments` contains `online`.