# Shamil Money / شامل موني

Method ID: `12`. Payment type: `4`. Source reviewed: 2026-10-24. This is an archived-code contract, not a live-provider certification. Examples are illustrative partial schemas; placeholder values are not credentials or captured transactions.

## URLs

Base selector: `ApiShamilMoneyUrl`.

Active source fallback: `https://shamilmoney.com:7394/Interface/API/Ecommerce/`.

Active fallback labelled live; older shamilmoney.net host is commented.

Most legacy base constants are wrapped in `if (!defined(...))`; an earlier bootstrap definition can override the fallback. Hard-coded full-URL exceptions are called out above. Merchant JSON is not automatically a base-URL override.

| Operation | HTTP method | Full URL | Use |
| --- | --- | --- | --- |
| Token | POST | `https://shamilmoney.com:7394/Interface/API/Ecommerce/token` | Form-encoded OAuth password grant. |
| Initiate | POST | `https://shamilmoney.com:7394/Interface/API/Ecommerce/WithdrawalReq` | JSON withdrawal initiation. |
| Confirm | POST | `https://shamilmoney.com:7394/Interface/API/Ecommerce/WithdrawalCom` | JSON confirmation. |
| Status | POST | `https://shamilmoney.com:7394/Interface/API/Ecommerce/ProcessQuery` | JSON transaction query. |
| Balance | POST | `https://shamilmoney.com:7394/Interface/API/Ecommerce/BalanceQuery` | Adapter helper. |


## Configuration fields

| Field / source setting | Meaning |
| --- | --- |
| AccountUserId | Merchant/agent/client identifier where used; stored in ElectronicPaymentAccountApiInfo. |
| AccountUserName | Merchant login/account name; not the customer phone unless the provider contract specifically uses it. |
| AccountUserPassword | Merchant password/short code; keep server-side. |
| ShamilMoneyAccountPaymentSecretKey | Server constant mapped to OAuth client_secret. No JSON override for this secret is established by the inspected assignment. |
| ShamilMoneyAccountcertificatePassword / certificate path | Server transport/certificate settings when the certificate branch is used. |


Configuration location: merchant row `platform_payment_ways.ElectronicPaymentAccountApiInfo`, plus named server constants/transport files where stated. Common listing fields (`type`, titles, descriptions, icon, account_number, order_view, status, active) are documented in [00-common-contract.md](00-common-contract.md).

Authentication/transport: OAuth password grant sends grant_type=password, username, password, client_id and client_secret. Payment requests use its access_token/token_type.

## Customer and server inputs

| Field | Requirement | Meaning |
| --- | --- | --- |
| payment_account_id | Required | Customer mobile/account. |
| voucher | Required by backend at creation | Purchase code forwarded as cvv; the inspected Flutter form does not render this field for method 12. |
| code | Required at confirmation | Customer confirmation code forwarded as otpCode. |


## Payment flow

1. Reject creation if customer account or purchase code is missing. Authenticate the merchant.
2. POST WithdrawalReq with transaction number, customer mobile, amount, cvv and request/device metadata. Save initiation metadata; status 2.
3. POST WithdrawalCom with the saved transaction context, purchase code and customer otpCode.
4. Require valid ResponseObject.Result and confirmation wallet references; set payment_status=3 on successful confirmation.

## Provider requests

### Token

```json
{
  "grant_type": "password",
  "username": "<MERCHANT_USERNAME>",
  "password": "<MERCHANT_PASSWORD>",
  "client_id": "<MERCHANT_CLIENT_ID>",
  "client_secret": "<MERCHANT_CLIENT_SECRET>"
}
```

### Withdrawal core fields

```json
{
  "langNo": "1",
  "PRN": "<GENERATED_REQUEST_REFERENCE>",
  "dev_na": "<DEVICE_NAME>",
  "client_ip": "<REQUEST_IP>",
  "dev_type": "<DEVICE_TYPE>",
  "user_name": "<MERCHANT_USERNAME>",
  "transNo": "<ORDER_REFERENCE>",
  "customerMobile": "<CUSTOMER_MOBILE>",
  "amount": "1000",
  "notes": "فاتورة مشتريات",
  "otpCode": "<CUSTOMER_OTP_OR_EMPTY_AT_INITIATION>",
  "cvv": "<CUSTOMER_PURCHASE_CODE>"
}
```

The examples show fields used by the archived adapter. Additional transport headers, derived identifiers and conditional helper-operation fields must be read with the source evidence below. Secrets and calculated security values are supplied/generated server-side.

## Provider responses and success rules

### Token — consumed fields

```json
{
  "access_token": "<ACCESS_TOKEN>",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "<SCOPE>"
}
```

### Payment — consumed fields

```json
{
  "ResponseObject": {
    "Result": {
      "ErrorNo": "1",
      "ErrorNa": "<PROVIDER_MESSAGE>"
    },
    "Wallet": {
      "transNo": "<TRANSACTION_NUMBER>",
      "Ref_No": "<PROVIDER_REFERENCE>"
    }
  }
}
```

- Requires a nonempty ResponseObject and Result. A nonempty ErrorNo other than "1" is an error.
- Confirmation additionally requires ResponseObject.Wallet with nonempty transNo and Ref_No. Initiation can retain the application order number as transNo; do not require a Wallet block at initiation simply because confirmation needs it.
- The normalized wrapper retains error/Message, transNo/Ref_No and request references; balance-query/status paths also parse reasons/details/msgId when present.

## Adapter result returned to the application layer

```json
{
  "error": false,
  "TimeOut": false,
  "Message": "<NORMALIZED_MESSAGE>",
  "Response": {
    "<provider-fields>": "<RAW_PROVIDER_RESPONSE>"
  }
}
```

This is a representative partial adapter result, not the public Flutter response. Keys are conditional and provider-specific. `error=true` or `TimeOut=true` prevents treating an initiation/confirmation as successful; transport errors can return before all keys exist. RequestType, saved references, token/cache metadata and provider-specific values may also be present. Raw merchant credentials/request logs must not be included in a customer-facing response.

## Application API requests and responses

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

`APP_API_BASE` is supplied by Firebase Remote Config key `api_url` in the archived Flutter app. The resolved deployment value is not present in the reviewed source; use that runtime value rather than inventing a host. These paths belong to Yemen Snack Food, not Sharqiah v1 driver APIs.

Create: `POST {APP_API_BASE}/orders.php?action=add_order`, using multipart form data. The JSON below is a readable representation of those form fields; `items` is JSON-encoded text. The server calculates the amount.

```json
{
  "address_id": "<OWNED_ADDRESS_ID>",
  "delivery_time": "<DELIVERY_OPTION>",
  "items": "[{\"id\":1,\"quantity\":1}]",
  "payment_id": 12,
  "payment_account_id": "<CUSTOMER_WALLET_OR_MOBILE>",
  "voucher": "<CUSTOMER_PURCHASE_CODE>"
}
```

Change method/details: `POST {APP_API_BASE}/orders.php?action=add_payment_info`, with `order_id`, `payment_id` and the relevant customer fields above. Changes are limited to early eligible orders and unconfirmed payment state; confirmation independently rejects ineligible/already-confirmed orders.

Confirm: `POST {APP_API_BASE}/orders.php?action=SendConfirmPayment` with form fields:

```json
{
  "order_id": "<ORDER_ID>",
  "code": "<CUSTOMER_OTP>"
}
```

Illustrative **partial** create response (business success, not proof of settlement):

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

Expected confirmed order state: `order_payment_status=3`. The confirm endpoint may return a message without an order object; Flutter reloads the order.

Business failure shape, illustrative and partial:

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

See [the common contract](00-common-contract.md) for auth, status meanings, shared fields and response-layer differences.


## Persistence, cancellation and implementation limits

Payment initiation uses `platform_orders_temporary_storage` and electronic-payment temporary metadata. Later operations load saved transaction references from electronic-payment metadata. The archive also uses filesystem caches; these are implementation details, not proof of atomicity or idempotency.

- Frontend/backend mismatch: Flutter only renders checkout vouchers for methods 9 and 14, while the backend also requires a purchase code for 12.
- Balance-query code and disabled diagnostic branches are not normal checkout steps.

## Source evidence

- Token fields: [functions/FunctionsPaymentShamilMoneyAcount.php:5010](</Users/ayman/Documents/Old Mac Data/Downloads/yemensnackfood/functions/FunctionsPaymentShamilMoneyAcount.php:5010>)

- Withdrawal fields: [functions/FunctionsPaymentShamilMoneyAcount.php:5474](</Users/ayman/Documents/Old Mac Data/Downloads/yemensnackfood/functions/FunctionsPaymentShamilMoneyAcount.php:5474>)

- Response requirements: [functions/FunctionsPaymentShamilMoneyAcount.php:9168](</Users/ayman/Documents/Old Mac Data/Downloads/yemensnackfood/functions/FunctionsPaymentShamilMoneyAcount.php:9168>)

- URL assignment: [functions/FunctionsPaymentShamilMoneyAcount.php:4684](</Users/ayman/Documents/Old Mac Data/Downloads/yemensnackfood/functions/FunctionsPaymentShamilMoneyAcount.php:4684>)

- URL assignment: [functions/FunctionsPaymentShamilMoneyAcount.php:4788](</Users/ayman/Documents/Old Mac Data/Downloads/yemensnackfood/functions/FunctionsPaymentShamilMoneyAcount.php:4788>)

- URL assignment: [functions/FunctionsPaymentShamilMoneyAcount.php:4798](</Users/ayman/Documents/Old Mac Data/Downloads/yemensnackfood/functions/FunctionsPaymentShamilMoneyAcount.php:4798>)

- URL assignment: [functions/FunctionsPaymentShamilMoneyAcount.php:4803](</Users/ayman/Documents/Old Mac Data/Downloads/yemensnackfood/functions/FunctionsPaymentShamilMoneyAcount.php:4803>)

- URL assignment: [functions/FunctionsPaymentShamilMoneyAcount.php:4809](</Users/ayman/Documents/Old Mac Data/Downloads/yemensnackfood/functions/FunctionsPaymentShamilMoneyAcount.php:4809>)

- URL assignment: [functions/FunctionsPaymentShamilMoneyAcount.php:4814](</Users/ayman/Documents/Old Mac Data/Downloads/yemensnackfood/functions/FunctionsPaymentShamilMoneyAcount.php:4814>)

- URL assignment: [functions/FunctionsPaymentShamilMoneyAcount.php:4827](</Users/ayman/Documents/Old Mac Data/Downloads/yemensnackfood/functions/FunctionsPaymentShamilMoneyAcount.php:4827>)

- Checkout dispatch: [connect/v1/OrderManagementPaymentWaysElectronic/AddOrder-PaymentSendInset.php:13889](</Users/ayman/Documents/Old Mac Data/Downloads/yemensnackfood/connect/v1/OrderManagementPaymentWaysElectronic/AddOrder-PaymentSendInset.php:13889>)

- Customer validation/configuration gate: [connect/v1/contains-orders/add_order.php:926](</Users/ayman/Documents/Old Mac Data/Downloads/yemensnackfood/connect/v1/contains-orders/add_order.php:926>)

- Flutter field selection: [lib/src/view/components/form_fields/payment_form_fields.dart:65](</Users/ayman/Documents/Old Mac Data/flutter_projects/platform/yemen_snack_food/lib/src/view/components/form_fields/payment_form_fields.dart:65>)
