# Shared Yemen Snack Food payment contract

Reviewed on 2026-10-24 from the archived PHP backend and Flutter app. This folder documents existing source behavior, not current official provider documentation, live availability, or new Sharqiah endpoints. No payment was executed. Active source code was distinguished from PHP comments and disabled test/helper branches. Real credentials, certificates and private keys are omitted.

## Source locations

- Backend: `/Users/ayman/Documents/Old Mac Data/Downloads/yemensnackfood`.
- Flutter: `/Users/ayman/Documents/Old Mac Data/flutter_projects/platform/yemen_snack_food`.
- The per-provider source links point into these local archives. They will need remapping on another computer.

## Application URLs

The archived Flutter default for `APP_API_BASE` is **`https://platformdgtl.com/yemensnackfood/connect/v1/`**, set in Remote Config defaults. Fetched Remote Config can override it; this is a source default, not a verified live deployment. Trim the trailing slash when combining it with the paths below. Source: [lib/src/controllers/splash_controller.dart:234](</Users/ayman/Documents/Old Mac Data/flutter_projects/platform/yemen_snack_food/lib/src/controllers/splash_controller.dart:234>).

The Flutter API base is `FirebaseRemoteConfig.instance.getString('api_url')`; the resolved deployment URL is not stored in the inspected getter, but the default value is documented above. `{APP_API_BASE}` below is that runtime base, trimmed before joining paths. Do not substitute a guessed production domain.

| Operation | HTTP | URL |
| --- | --- | --- |
| List methods | POST | `{APP_API_BASE}/payment.php?action=get_all` |
| Create order | POST | `{APP_API_BASE}/orders.php?action=add_order` |
| Change payment / submit transfer details | POST | `{APP_API_BASE}/orders.php?action=add_payment_info` |
| Confirm electronic payment | POST | `{APP_API_BASE}/orders.php?action=SendConfirmPayment` |
| Cancel order | POST | `{APP_API_BASE}/orders.php?action=cancel_order` |

The list request may supply `address_id`. Calls use the existing authenticated customer context; provider merchant credentials never belong in these Flutter form fields. This audit does not invent a standalone auth header/token format: use the archived app's API/auth pipeline.

## Method configuration

`platform_payment_ways` owns the configured method rows. Custom bank/remittance/no-detail rows can exist in the database in addition to hard-coded IDs documented here.

| Field | Purpose |
| --- | --- |
| `id` | Concrete method ID, e.g. 5=One Cash. |
| `type` | Flow category: 1=no extra details, 2=bank/reference, 3=company+remittance, 4=electronic, 5=legacy rewards, 6=internal wallet. |
| `title_arabic`, `title_english` | Localized method names. |
| `description_arabic`, `description_english` | Customer instructions. |
| `account_number` | Displayed merchant account for manual methods. |
| `company_name_arabic`, `company_name_english` | Configured company labels where used. |
| `icon`, `order_view` | Icon and sorting. |
| `status=1`, `active=0` | Listing/checkout availability convention. |
| `ElectronicPaymentAccountApiInfo` | Serialized merchant configuration; usually AccountUserId, AccountUserName, AccountUserPassword plus provider-specific fields. |

URL constants and certificate/cryptographic constants are separate server settings; adding a `base_url` JSON property does not change legacy adapters that never read it. Each provider file explains actual URL selection. Enabled runtime database rows and previously-defined bootstrap constants were not queried.

## Application request fields

| Field | Who supplies it | Meaning |
| --- | --- | --- |
| `payment_id` | Customer selection | Selects the configured method. |
| `payment_account_id` | Customer, when needed | Wallet/mobile/account, or PIN for Haseb. |
| `voucher` | Customer, when needed | Purchase code for voucher flows. |
| `code` | Customer at confirmation | OTP or purchase voucher depending on method. |
| `transfer_number` | Customer for manual payment | Deposit reference / depositor description / remittance number. |
| `transfer_company` | Customer for remittance | Exchange/remittance company. |
| `transaction_image` / `transfare_attach_file` | Optional backend upload | Receipt attachment aliases; inspected Flutter OrderVM does not send an attachment. |
| `address_id`, `delivery_time`, `items`, `notes` | Existing order checkout | Shared checkout data. `items` is JSON-encoded text inside multipart form data. |
| `order_id` | Existing order | Required when changing/confirming an existing order. |

Order amount, currency context, customer ID, merchant IDs and transaction references are derived/loaded by the backend. Do not trust a customer-supplied amount or use a new OTP against another order's saved reference. The source has additional order options; the examples intentionally focus on the payment contract.

## Three response layers

1. Provider response: vendor-specific JSON, token result or HTTP error; each file describes keys actually consumed.
2. PHP adapter result: typically `error`, `TimeOut`, `Message`, `Response`, references and cache metadata. It is not the Flutter envelope.
3. Application envelope: `status`, `message`, optional `result`. Business `status=0` means the API operation succeeded; Flutter treats status 1 as error and status 2 as an authentication-required case where applicable.

Illustrative partial application success:

```json
{"status":0,"message":"<APPLICATION_MESSAGE>","result":{"order_id":123,"order_payment_id":5,"order_payment_type":4,"order_payment_status":2}}
```

Illustrative application error:

```json
{"status":1,"message":"<VALIDATION_OR_PROVIDER_ERROR>"}
```

The confirm action may return a message without an order; Flutter reloads the order. Do not require every response to contain result, and do not interpret top-level status=0 as paid money.

| Order payment status | Meaning |
| --- | --- |
| 1 | Unpaid. |
| 2 | Not confirmed / pending confirmation. |
| 3 | Confirmed. |
| 4 | Reversed. |

Confirmation and payment changes are restricted to eligible early order states; already-confirmed, cancelled and delivered cases have their own rejection/already-processed messages. Check order state independently from payment state.

## Currency and cancellation boundaries

The inspected installation uses local currency IDs 3/4 for old/new Yemeni rial. Most electronic checkout branches require ID 3; Haseb validates a verified provider zone and its old/new-rial compatibility. Mastercard uses the converted USD total and rejects values below USD 10. Provider currency identifiers such as CashPay currencyID=2 and Jaib currencyID=1 are separate from the application's currency IDs.

Refund helper methods are documented as capabilities only unless the cancellation route actually invokes them. The internal wallet reverses its own ledger deductions. The customer cancellation route contains a Pyes-specific attempted refund with a one-day restriction, but the adapter rejects the requested operation name; see 07-pyes.md. Filesystem caching and repeated SQL statements are not a proof of transactional safety or duplicate-charge prevention.

## Example and configuration conventions

All request/response JSON examples are illustrative partial schemas based on fields read/written in source. Amount 1000, IDs, timestamps and TTL 3600 are example values, not captured responses or claimed vendor defaults. Optional fields can be absent. The full official schema, every provider error code, production URLs and enabled methods cannot be certified from this archive alone. Preserve source field casing/spelling. Known parser spelling defects and missing client flows are noted in the relevant files.

## Source evidence

- [lib/src/core/values/app_config.dart:16](</Users/ayman/Documents/Old Mac Data/flutter_projects/platform/yemen_snack_food/lib/src/core/values/app_config.dart:16>)
- [lib/src/data/providers/api/api_provider.dart:125](</Users/ayman/Documents/Old Mac Data/flutter_projects/platform/yemen_snack_food/lib/src/data/providers/api/api_provider.dart:125>)
- [connect/v1/payment.php:465](</Users/ayman/Documents/Old Mac Data/Downloads/yemensnackfood/connect/v1/payment.php:465>)
- [connect/v1/_function.php:2199](</Users/ayman/Documents/Old Mac Data/Downloads/yemensnackfood/connect/v1/_function.php:2199>)
- [connect/v1/contains-orders/add_order.php:1933](</Users/ayman/Documents/Old Mac Data/Downloads/yemensnackfood/connect/v1/contains-orders/add_order.php:1933>)
- [connect/v1/contains-orders/add_order.php:2303](</Users/ayman/Documents/Old Mac Data/Downloads/yemensnackfood/connect/v1/contains-orders/add_order.php:2303>)
- [connect/v1/contains-orders/SendConfirmPayment.php:163](</Users/ayman/Documents/Old Mac Data/Downloads/yemensnackfood/connect/v1/contains-orders/SendConfirmPayment.php:163>)
