# Pyes / بيس — Al-Amal Bank

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

Active source fallback: `https://banksys.alamalbank.com/ords/amb`.

The active fallback has no trailing slash; route strings begin with /. Older hosts/ports in comments are not active defaults.

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 |
| --- | --- | --- | --- |
| Login | GET | `https://banksys.alamalbank.com/ords/amb/auth/login` | Merchant authentication; source uses GET, not POST. |
| Request verification | POST | `https://banksys.alamalbank.com/ords/amb/api/v1/verification_pos` | Initiation/verification. |
| Pay | POST | `https://banksys.alamalbank.com/ords/amb/api/v1/payment_pos` | Confirmation/payment. |
| Account report | POST | `https://banksys.alamalbank.com/ords/amb/api/v1/account_transaction_report` | 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. |
| agentUser / fromAccount / toPosId / currencyId | Derived wire values for P_USER_NAME, P_FROM_ACCOUNT_ID, P_TO_POS_ID and p_cur_id. Inspect the caller/adapter mapping when provisioning the merchant POS; these are not extra free-form Flutter fields. |


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: GET login uses Authorization: Basic base64(AccountUserName + ":" + AccountUserPassword), P_SHRT_CODE: AccountUserName and P_DEVICE_NAM: AccountUserId. Subsequent requests use the stored access token.

## Customer and server inputs

| Field | Requirement | Meaning |
| --- | --- | --- |
| payment_account_id | Required | Customer source account/wallet. |
| code | Required at confirmation | Customer verification code; converted to integer for P_CONFIRM_CODE. |


## Payment flow

1. Authenticate merchant, submit verification_pos for customer source account and order amount. Initial confirmation code is 0; order remains status 2.
2. Customer supplies the received verification code.
3. Submit payment_pos with P_CONFIRM_CODE and the saved invoice/customer/POS data.
4. Apply the operation-specific CODE acceptance rules and update payment_status=3 only after confirmation succeeds.

## Provider requests

### Verification / payment

```json
{
  "P_USER_NAME": "<AGENT_USERNAME>",
  "P_COM_ID": 1,
  "P_FROM_ACCOUNT_ID": "<CUSTOMER_ACCOUNT>",
  "P_TO_POS_ID": "<MERCHANT_POS_ID>",
  "P_AMOUNT": 1000,
  "p_cur_id": "<PROVIDER_CURRENCY_ID>",
  "P_CONFIRM_CODE": 0,
  "P_REF_INVOICE_ID": "<ORDER_REFERENCE>",
  "P_LANG": "AR"
}
```

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

### Login — consumed fields

```json
{
  "CODE": "1",
  "token": "<ACCESS_TOKEN>",
  "expires_in": 3600,
  "message": "<PROVIDER_MESSAGE>"
}
```

### Provider response — consumed fields

```json
{
  "CODE": "1",
  "MSG": "<PROVIDER_MESSAGE>",
  "ref_req_id": "<VERIFICATION_REFERENCE>"
}
```

- Login separately requires CODE="1"; it reads token, expires_in and message. The accepted payment/verification codes below do not apply to login.
- VerificationRequest accepts CODE "0" or "1"; OrderInfoRequest accepts "1" or "6". These are separate branch rules, not a universal success-code list.
- CODE "6" has special handling that extracts an OTP-related value from MSG into ConfirmUserOtpInput. Preserve the exact branch semantics when reviewing this legacy behavior.
- The wrapper returns Code, Message, RefReqId and order/customer metadata.

## 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": 7,
  "payment_account_id": "<CUSTOMER_WALLET_OR_MOBILE>"
}
```

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": 7,
    "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.

- Customer cancellation attempts OperationRefoundPaymentRequest and rejects cancellation after one day from the stored payment timestamp.
- The adapter allowlist only accepts VerificationRequest, OrderInfoRequest and AccountTransactionReport; the requested refund operation is rejected. The cancellation/refund path is inconsistent.

## Source evidence

- Login URL: [functions/FunctionsPaymenPyesElamalBankAcount.php:1361](</Users/ayman/Documents/Old Mac Data/Downloads/yemensnackfood/functions/FunctionsPaymenPyesElamalBankAcount.php:1361>)

- Payment fields: [functions/FunctionsPaymenPyesElamalBankAcount.php:3907](</Users/ayman/Documents/Old Mac Data/Downloads/yemensnackfood/functions/FunctionsPaymenPyesElamalBankAcount.php:3907>)

- Response checks: [functions/FunctionsPaymenPyesElamalBankAcount.php:5049](</Users/ayman/Documents/Old Mac Data/Downloads/yemensnackfood/functions/FunctionsPaymenPyesElamalBankAcount.php:5049>)

- Login headers: [functions/FunctionsPaymenPyesElamalBankAcount.php:1800](</Users/ayman/Documents/Old Mac Data/Downloads/yemensnackfood/functions/FunctionsPaymenPyesElamalBankAcount.php:1800>)

- Login response: [functions/FunctionsPaymenPyesElamalBankAcount.php:2297](</Users/ayman/Documents/Old Mac Data/Downloads/yemensnackfood/functions/FunctionsPaymenPyesElamalBankAcount.php:2297>)

- Payment bearer header: [functions/FunctionsPaymenPyesElamalBankAcount.php:4499](</Users/ayman/Documents/Old Mac Data/Downloads/yemensnackfood/functions/FunctionsPaymenPyesElamalBankAcount.php:4499>)

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

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

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

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

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

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

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

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

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

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

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