# Jawali / جوالي

Method ID: `10`. 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: `ApiJawaliUrl`.

Active source fallback: `https://app.wecash.com.ye:8493/`.

Active fallback; IP alternatives in comments are not used by default.

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 |
| --- | --- | --- | --- |
| OAuth login | POST | `https://app.wecash.com.ye:8493/paygate/oauth/token` | Form encoded. |
| Wallet authentication | POST | `https://app.wecash.com.ye:8493/paygate/v1/ws/callWS` | serviceName PAYWA.WALLETAUTHENTICATION. |
| Purchase inquiry | POST | `https://app.wecash.com.ye:8493/paygate/v1/ws/callWS` | serviceName PAYAG.ECOMMERCEINQUIRY. |
| Execute purchase | POST | `https://app.wecash.com.ye:8493/paygate/v1/ws/callWS` | serviceName PAYAG.ECOMMCASHOUT. |
| Transaction check | POST | `https://app.wecash.com.ye:8493/paygate/v1/ws/callWS` | serviceName PAYWA.AGENTCHECKSTATUS. |
| Refund | POST | `https://app.wecash.com.ye:8493/paygate/v1/ws/callWS` | serviceName PAYAG.ECOMMERCEREFUND; adapter capability. |


## 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. |
| AccountWalletIdn | Required agent wallet identifier for wallet authentication and merchant operations. |
| AccountWalletPwd | Required agent-wallet password, distinct from merchant login password. |
| OAuth client_id / client_secret / scope | Adapter contains fixed client metadata (restapp/read). Treat as provider integration parameters; no credential values are reproduced here. |


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 creates merchant access/refresh tokens. A second wallet-authentication request creates wallet accessToken. Both merchant and wallet authentication context are used in JSON callWS requests.

## Customer and server inputs

| Field | Requirement | Meaning |
| --- | --- | --- |
| payment_account_id | Required | Customer receiverMobile. |
| voucher | Optional at creation; required to execute purchase | Flutter normally requests the purchase voucher in the subsequent confirmation sheet. |
| code | Required at confirmation | Mapped to purchase voucher, not a generic OTP execution call. |


## Payment flow

1. Authenticate the merchant, then authenticate AccountWalletIdn/AccountWalletPwd through WalletDomain.
2. Without a purchase voucher, retain a pending order with status 2. With wallet and voucher available, perform inquiry then cash-out.
3. Inquiry returns issuerTrxRef and amount information; retain issuerTrxRef, voucher, receiverMobile and wallet token.
4. Confirmation repeats/resumes inquiry and cash-out with the customer voucher. Successful execution sets status 3; direct successful voucher checkout may already set 3.

## Provider requests

### OAuth fields

```json
{
  "username": "<MERCHANT_USERNAME>",
  "password": "<MERCHANT_PASSWORD>",
  "grant_type": "password",
  "client_id": "<INTEGRATION_CLIENT_ID>",
  "client_secret": "<INTEGRATION_CLIENT_SECRET>",
  "scope": "read"
}
```

### callWS inquiry envelope — core fields

```json
{
  "header": {
    "serviceDetail": {
      "corrID": "<CORRELATION_ID>",
      "domainName": "MerchantDomain",
      "serviceName": "PAYAG.ECOMMERCEINQUIRY"
    },
    "signonDetail": {
      "clientID": "WeCash",
      "orgID": "<MERCHANT_ORG_ID>",
      "userID": "<MERCHANT_USERNAME>",
      "externalUser": "External User"
    },
    "messageContext": {
      "clientDate": "<TIMESTAMP>",
      "bodyType": "Clear"
    }
  },
  "body": {
    "agentWallet": "<AGENT_WALLET_ID>",
    "password": "<AGENT_WALLET_PASSWORD>",
    "voucher": "<CUSTOMER_VOUCHER>",
    "receiverMobile": "<CUSTOMER_MOBILE>",
    "accessToken": "<WALLET_ACCESS_TOKEN>",
    "refId": "<ORDER_REFERENCE>",
    "purpose": "فاتورة مشتريات"
  }
}
```

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

### OAuth — consumed fields

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

### callWS — consumed fields

```json
{
  "responseStatus": {
    "systemStatus": "0",
    "systemStatusDesc": "Success",
    "systemStatusDescNative": "<PROVIDER_MESSAGE>"
  },
  "responseBody": {
    "issuerTrxRef": "<ISSUER_REFERENCE>",
    "txnamount": 1000,
    "state": "<PROVIDER_STATE>",
    "updateTime": "<TIME>",
    "trxDate": "<DATE>"
  }
}
```

- callWS treats a non-null systemStatus other than "0", or a non-null systemStatusDesc other than "Success", as a failure.
- Wallet authentication reads responseBody.access_token, org_value and org_name. Cash-out uses saved issuerRef populated from inquiry issuerTrxRef.
- Do not invent universal state values: this archive reads state, but the full provider state catalogue is not established by a live transaction.

## 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": 10,
  "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_VOUCHER>"
}
```

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

```json
{
  "status": 0,
  "message": "<APPLICATION_MESSAGE>",
  "result": {
    "order_id": 123,
    "order_payment_id": 10,
    "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.

- Merchant wallet credentials and customer voucher are separate inputs.
- Refund helper presence does not establish automatic refund through the customer cancellation endpoint.

## Source evidence

- Wallet configuration: [functions/FunctionsPaymentJawaliAcount.php:2333](</Users/ayman/Documents/Old Mac Data/Downloads/yemensnackfood/functions/FunctionsPaymentJawaliAcount.php:2333>)

- OAuth fields: [functions/FunctionsPaymentJawaliAcount.php:3744](</Users/ayman/Documents/Old Mac Data/Downloads/yemensnackfood/functions/FunctionsPaymentJawaliAcount.php:3744>)

- JSON envelope: [functions/FunctionsPaymentJawaliAcount.php:3833](</Users/ayman/Documents/Old Mac Data/Downloads/yemensnackfood/functions/FunctionsPaymentJawaliAcount.php:3833>)

- Response status: [functions/FunctionsPaymentJawaliAcount.php:6558](</Users/ayman/Documents/Old Mac Data/Downloads/yemensnackfood/functions/FunctionsPaymentJawaliAcount.php:6558>)

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

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

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

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

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

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