# MyFatoorah — Backend Requirements for a Complete Mobile Flow

This file records the backend contract the mobile app needs in addition to the
normal create-order flow documented in `payment-flow.md`.

## Already consumed by the app

### 1. List payment methods

`GET /api/general/payments/myfatoorah/payment-methods`

- Must not require a user bearer token.
- Must accept `Agent-Token` and `Accept: application/json`.
- `data` must be a JSON array.
- Every item must contain a unique integer `payment_method_id`, localized names,
  `payment_method_code`, and `image_url`.
- Return only methods that are currently enabled and usable for the account and
  country. The app intentionally does not hard-code method IDs.

### 2. Create the order / checkout session

`POST /api/app/client/orders`

For any request containing at least one
`vendor_payments[{vendor_id}]=online`, the app sends the selected integer
`payment_method_id`. For wallet, deferred, COD, or a free order it does not send
that field.

The coupon field is `coupon_code` (not `code`).

When gateway payment is required, return:

```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/...",
    "amount": 10.79,
    "currency": "SAR"
  }
}
```

`payment_url` is mandatory whenever `data.status` is `pending_payment`.
For wallet, deferred, COD, or a free order, the existing immediate-success
response may keep `data: null`.

## Callback response required by the current WebView

MyFatoorah calls:

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

After verifying with MyFatoorah and creating the order exactly once, the
callback shown in the WebView must provide an unambiguous final result using
one of these contracts:

1. Redirect to `/api/general/payments/myfatoorah/success?...` or
   `/api/general/payments/myfatoorah/error?...`; or
2. Return JSON whose `status` is `success`, `completed`, or `paid` for success,
   and `failed`, `error`, or `cancelled` for failure.

Recommended JSON response:

```json
{
  "status": "success",
  "message": "Payment verified and order created successfully",
  "data": {
    "status": "completed",
    "reference": "CHK-XXXXXXXXXXXXXX",
    "order_group_id": 77
  }
}
```

The callback must be idempotent. Repeated callbacks for the same `reference`
must return the existing result and must never create duplicate orders.

## Missing endpoint needed for recovery and polling

The supplied flow says the app can poll by `reference`, but it does not define
that endpoint. Please add:

`GET /api/app/client/payments/myfatoorah/status?reference=CHK-...`

Headers: `Authorization: Bearer {token}`, `Agent-Token`, and
`Accept: application/json`.

Expected response:

```json
{
  "status": "success",
  "data": {
    "reference": "CHK-XXXXXXXXXXXXXX",
    "payment_status": "pending",
    "order_created": false,
    "order_group_id": null
  }
}
```

`payment_status` must be one of `pending`, `paid`, `failed`, `cancelled`, or
`expired`. When it is `paid`, `order_created` must be `true` and
`order_group_id` must be present.

This endpoint lets the app recover safely if it is closed during payment, the
callback page fails to render, or the gateway-to-backend callback completes
after the user returns to the app.