# Customer application wallet / محفظة العميل الداخلية

Method ID: `16`. Payment type: `6`. Reviewed from archived source on 2026-10-24. This is the application's own balance, separate from provider wallets such as One Cash and Easy.

## 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>).

Provider URL: **none**. No external wallet API, access token or provider merchant credentials are involved.

| Operation | HTTP | URL |
| --- | --- | --- |
| List methods and displayed balance | POST | `{APP_API_BASE}/payment.php?action=get_all` |
| Pay from balance when creating | POST | `{APP_API_BASE}/orders.php?action=add_order` |
| Change to/from wallet | POST | `{APP_API_BASE}/orders.php?action=add_payment_info` |
| Cancel eligible order | POST | `{APP_API_BASE}/orders.php?action=cancel_order` |

`APP_API_BASE` comes from Flutter's Firebase Remote Config key `api_url`; the runtime host was not verified.

## Configuration and stored fields

| Field / setting | Meaning |
| --- | --- |
| `SiteAllowCustomerWallet` | Feature gate for wallet listing/usage. |
| `platform_payment_ways.id=16`, `type=6` | Archived wallet method identity/category. |
| `status=1`, `active=0` | Enabled-row convention; use the shared localized labels/instructions. |
| `platform_users_wallet.user_id` | Owner of a ledger entry. |
| `type=1` / `type=2` | Credit / debit ledger entries, separate from payment category numbers. |
| `amount`, `status_deserved` | Entry value; only `status_deserved=1` participates in the active balance. |
| `order_id`, `payment_id` | Links a deduction/reversal to the order and method. |
| `platform_users.SumWalletAmount` | Cached user balance, recalculated after ledger changes. |
| `payment_account_balance` | Method-list balance exposed when wallet is enabled. |

Balance is active credits minus active debits. The creation path can begin from the cached user balance; a full re-read switch immediately before deduction is disabled in the inspected branch. Do not claim this is a verified atomic reservation.

## Required inputs

Customer supplies `payment_id=16`, shared checkout fields, and `order_id` when changing an existing order. No customer phone, external wallet ID, PIN, voucher or OTP is required. The server owns customer identity, order amount, available balance and deduction size.

## Payment flow

1. Confirm the wallet feature/method is enabled and load the customer's available balance.
2. Calculate invoice due. With positive balance, insert a debit for `min(available balance, invoice total)` linked to this order.
3. If the wallet covers the total, mark payment confirmed (`payment_status=3`). With partial coverage, leave the order unpaid (`payment_status=1`) for the remainder; the UI describes a cash remainder.
4. Recalculate active credits minus active debits and update `platform_users.SumWalletAmount`.
5. Changing to wallet can create an order-linked debit; changing away reverses the prior wallet deduction. Both paths have order/payment eligibility checks.
6. Eligible cancellation restores the wallet contribution through ledger-entry state changes. It does not call an external gateway.

Example: invoice 1,000 and available wallet balance 600 means wallet debit 600 and cash remainder 400; order payment is still unpaid. Available balance 1,200 means wallet debit 1,000, remaining account balance 200, and order payment confirmed.

```mermaid
flowchart TD
    A[Calculate invoice and wallet balance] --> B{Wallet covers invoice?}
    B -->|Yes| C[Debit invoice amount]
    C --> D[Payment confirmed: 3]
    B -->|Partial coverage| E[Debit available balance]
    E --> F[Cash remainder: payment unpaid 1]
    D --> G[Recalculate cached wallet balance]
    F --> G
```

## Request example

`POST {APP_API_BASE}/orders.php?action=add_order`, multipart form fields represented as JSON for readability:

```json
{"address_id":"<OWNED_ADDRESS_ID>","delivery_time":"<DELIVERY_OPTION>","items":"[{\"id\":1,\"quantity\":1}]","payment_id":16}
```

For changing an existing eligible order: `POST {APP_API_BASE}/orders.php?action=add_payment_info` with `order_id` and `payment_id=16`. No separate provider confirmation request exists.

## Responses and displayed amounts

No provider response/adapter wrapper exists. Illustrative partial application response for the 600/1,000 example:

```json
{"status":0,"message":"<APPLICATION_MESSAGE>","result":{"order_id":123,"order_payment_id":16,"order_payment_type":6,"order_payment_status":1,"order_wallet_price_paying":600,"order_wallet_price_remaining":400,"order_wallet_price_due":1000}}
```

| Order field | Meaning in inspected order serializer |
| --- | --- |
| `order_wallet_price_paying` | Active order-linked wallet deduction. |
| `order_wallet_price_due` | Full invoice total in this calculation, not remaining cash. |
| `order_wallet_price_remaining` | Invoice total minus wallet contribution; source takes its absolute value if negative. This is not the remaining wallet account balance. |

Full coverage has `order_payment_status=3`. Validation/order-state errors follow `{ "status": 1, "message": "<ERROR>" }`. A successful API call must be distinguished from full invoice coverage.

## Cancellation, credits and limitations

Cancellation first inserts a credit, deactivates the original order-linked debit entries (`status_deserved=2`), and, if that update affects rows, deactivates the newly inserted credit too. The normal effect is balance restoration by excluding the original debit; it is not a new active credit plus a removed debit. Previously confirmed wallet payment is marked reversed (`payment_status=4`) in that branch.

Administrative wallet credits exist in the archived admin system. This audit found no external provider checkout that automatically tops up this internal balance. SQL statements/cached balances are source behavior; no concurrency, crash-recovery or live end-to-end test was performed.

## Source evidence

- [connect/v1/contains-orders/add_order.php:6424](</Users/ayman/Documents/Old Mac Data/Downloads/yemensnackfood/connect/v1/contains-orders/add_order.php:6424>)
- [connect/v1/contains-orders/add_order.php:6450](</Users/ayman/Documents/Old Mac Data/Downloads/yemensnackfood/connect/v1/contains-orders/add_order.php:6450>)
- [connect/v1/contains-orders/add_order.php:6491](</Users/ayman/Documents/Old Mac Data/Downloads/yemensnackfood/connect/v1/contains-orders/add_order.php:6491>)
- [connect/v1/contains-orders/add_payment_info.php:1887](</Users/ayman/Documents/Old Mac Data/Downloads/yemensnackfood/connect/v1/contains-orders/add_payment_info.php:1887>)
- [connect/v1/contains-orders/add_payment_info.php:1968](</Users/ayman/Documents/Old Mac Data/Downloads/yemensnackfood/connect/v1/contains-orders/add_payment_info.php:1968>)
- [connect/v1/contains-orders/cancel_order.php:858](</Users/ayman/Documents/Old Mac Data/Downloads/yemensnackfood/connect/v1/contains-orders/cancel_order.php:858>)
- [connect/v1/GetOrderRowDetails.php:7505](</Users/ayman/Documents/Old Mac Data/Downloads/yemensnackfood/connect/v1/GetOrderRowDetails.php:7505>)
- [Ya@dm_n/accounts-users-wallet.php:850](</Users/ayman/Documents/Old Mac Data/Downloads/yemensnackfood/Ya@dm_n/accounts-users-wallet.php:850>)
