# Easy / إيزي

Method ID: `18`. 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: `ApiEasyWalletUrl / EasyWalletPayment::$PublicApiBaseUrl`.

Active source fallback: `https://api-test.tharwatt.com:5223`.

Both the class fallback and the active init constant use a hostname containing api-test. One source comment labels that same constant live; that comment is not evidence that it is production. SetApiBaseUrl/static base can override the class fallback.

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://api-test.tharwatt.com:5223/accounts/v1/authenticate/token` | client_credentials. |
| Initiate | POST | `https://api-test.tharwatt.com:5223/v1/transactionrequests` | X-API-ServiceName: initiate. |
| Confirm | POST | `https://api-test.tharwatt.com:5223/v1/transactions` | X-API-ServiceName: confirm. |
| Issue payment code helper | POST | `https://api-test.tharwatt.com:5223/v1/transactionrequests` | Different service headers: pos.wallets.vouchers / issue; not normal checkout. |
| Capture payment code helper | POST | `https://api-test.tharwatt.com:5223/v1/transactions` | Different service headers: pos.wallets.vouchers / capture. |
| Payment request status helper | GET | `https://api-test.tharwatt.com:5223/v1/transactionrequests?requestId={requestId}` | Request status; requests / status headers. |
| Transaction status helper | GET | `https://api-test.tharwatt.com:5223/v1/transactions?referenceNumber={referenceNumber}&requestDate={optionalDate}` | referenceNumber required; requestDate optional; transactions / status headers. |
| Balance helper | GET | `https://api-test.tharwatt.com:5223/accounts/v1/balance` | Class supplies currencyCode data; not normal checkout. |


## Configuration fields

| Field / source setting | Meaning |
| --- | --- |
| AccountUserId | Actual clientId argument passed by the dispatcher. The preliminary gate also permits AccountUserName, but the constructor still receives AccountUserId; provision this ID explicitly. |
| AccountUserPassword | Mapped into the class clientSecret argument. |
| clientId / clientSecret | Constructor parameters used for client_credentials token requests; exact merchant values are omitted. |
| ApiEasyWalletUrl / PublicApiBaseUrl / SetApiBaseUrl | Server URL selection; class default is used if no explicit base is supplied. |


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: Client credentials are sent to the token endpoint. Payment calls use its bearer context and X-API-Domain: payment, X-API-SubDomain: pos.wallets.payments, and the operation-specific X-API-ServiceName. Token fields are application/x-www-form-urlencoded; the JSON token example is a readable field map, not the literal encoded body.

## Customer and server inputs

| Field | Requirement | Meaning |
| --- | --- | --- |
| payment_account_id | Required | Customer wallet accountId. |
| code | Required at confirmation | Customer OTP forwarded as oneTimeCode. |
| Customer profile/KYC | Server supplied | Name components, mobile, application user ID and gender are built by the dispatcher. |


## Payment flow

1. Instantiate EasyWalletPayment with merchant client credentials; acquire/reuse the token.
2. Build initiatePayment with generated requestId/referenceNumber, YER amount, source/beneficiary and senderKYC.
3. Save entity.requestId, referenceNumber, unifiedToken (stored as authId), amount, reSourceToken, currencyCode and expiryDate; status 2.
4. Confirm with the saved references/authId, current amount/currency and customer oneTimeCode. The dispatcher checks stored expiry metadata and can initiate again if the confirmation context needs renewal.
5. Successful confirmation sets payment_status=3.

## Provider requests

### Token

```json
{
  "grant_type": "client_credentials",
  "client_id": "<MERCHANT_CLIENT_ID>",
  "client_secret": "<MERCHANT_CLIENT_SECRET>"
}
```

### Initiate — core fields

```json
{
  "requestId": "<GENERATED_REQUEST_ID>",
  "referenceNumber": "<GENERATED_REFERENCE>",
  "currencyCode": "YER",
  "amount": 1000,
  "amountType": 1,
  "captureMode": "MANUAL",
  "isBeneficiaryInitiated": true,
  "source": {
    "organizationCode": "Easy",
    "accountType": "WalletId",
    "accountId": "<CUSTOMER_WALLET>"
  },
  "beneficiary": {
    "organizationCode": "Easy",
    "accountType": "MerchantId",
    "accountId": "<VALUE_CURRENTLY_TAKEN_FROM_PAYMENT_ACCOUNT_ID>"
  },
  "senderKYC": {
    "firstName": "<FIRST_NAME>",
    "secondName": "<SECOND_NAME>",
    "thirdName": "<THIRD_NAME>",
    "familyName": "<FAMILY_NAME>",
    "mobileNumber": "<CUSTOMER_MOBILE>",
    "IdNumber": "<APPLICATION_USER_ID>",
    "IdType": "1",
    "gendar": "<GENDER>"
  }
}
```

### Confirm — core fields

```json
{
  "requestId": "<SAVED_REQUEST_ID>",
  "referenceNumber": "<SAVED_REFERENCE_NUMBER>",
  "currencyCode": "YER",
  "amount": 1000,
  "organizationCode": "Easy",
  "autherizationType": "Token",
  "autherizationId": "<SAVED_AUTH_ID>",
  "oneTimeCode": "<CUSTOMER_OTP>"
}
```

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 — raw provider fields consumed by the class

```json
{
  "success": true,
  "entity": {
    "access_token": "<ACCESS_TOKEN>",
    "expires_in": 3600
  }
}
```

### Initiate — raw provider fields consumed through the class

```json
{
  "success": true,
  "message": "<PROVIDER_MESSAGE>",
  "responseCode": "<PROVIDER_CODE>",
  "entity": {
    "requestId": "<REQUEST_ID>",
    "referenceNumber": "<REFERENCE>",
    "unifiedToken": "<AUTHORIZATION_TOKEN>",
    "amount": 1000,
    "reSourceToken": "<RESOURCE_TOKEN>",
    "currencyCode": "YER",
    "expiryDate": "<EXPIRY_DATE>"
  }
}
```

- EasyWalletPayment.sendCurl wraps decoded provider JSON as {success, message, data: decodedProviderResponse}. Thus class-level data.entity is provider-level entity; the class success flag requires the raw provider success to be boolean true. This extra wrapper is distinct from the application status/message/result envelope.
- Initiation reads success from the outer response or data, then requires nonempty entity.requestId, referenceNumber and unifiedToken.
- Confirmation likewise evaluates success/message/responseCode and the class result. It is unsafe to invent a full confirmation entity schema not consumed by this code.
- The normalized saved context renames unifiedToken to authId. Confirmation uses the source spellings autherizationType/autherizationId and reSourceToken; these are not corrected spellings in this report.

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

- Archived source sets beneficiary.accountId from the customer payment_account_id, even though beneficiary.accountType is MerchantId. This mapping needs confirmation before implementing a new integration.
- Additional class methods include issuePaymentCode, getPaymentRequestStatus, getTransactionStatus and getBalance; they are helper capabilities, not all steps of checkout.
- Legacy fallback functions are referenced in disabled/test branches; the active flow uses the class.

## Source evidence

- Constructor: [functions/payment-gateways-in-Yemen/EasyWalletPayment.php:137](</Users/ayman/Documents/Old Mac Data/Downloads/yemensnackfood/functions/payment-gateways-in-Yemen/EasyWalletPayment.php:137>)

- Token route: [functions/payment-gateways-in-Yemen/EasyWalletPayment.php:1141](</Users/ayman/Documents/Old Mac Data/Downloads/yemensnackfood/functions/payment-gateways-in-Yemen/EasyWalletPayment.php:1141>)

- Initiation: [functions/payment-gateways-in-Yemen/EasyWalletPayment.php:1288](</Users/ayman/Documents/Old Mac Data/Downloads/yemensnackfood/functions/payment-gateways-in-Yemen/EasyWalletPayment.php:1288>)

- Confirmation: [functions/payment-gateways-in-Yemen/EasyWalletPayment.php:1322](</Users/ayman/Documents/Old Mac Data/Downloads/yemensnackfood/functions/payment-gateways-in-Yemen/EasyWalletPayment.php:1322>)

- URL assignment: [functions/payment-gateways-in-Yemen/EasyWalletPayment.php:1141](</Users/ayman/Documents/Old Mac Data/Downloads/yemensnackfood/functions/payment-gateways-in-Yemen/EasyWalletPayment.php:1141>)

- URL assignment: [functions/payment-gateways-in-Yemen/EasyWalletPayment.php:1443](</Users/ayman/Documents/Old Mac Data/Downloads/yemensnackfood/functions/payment-gateways-in-Yemen/EasyWalletPayment.php:1443>)

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

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

- Exact caller request/confirmation payloads: [connect/v1/OrderManagementPaymentWaysElectronic/AddOrder-PaymentSendInset.php:639](</Users/ayman/Documents/Old Mac Data/Downloads/yemensnackfood/connect/v1/OrderManagementPaymentWaysElectronic/AddOrder-PaymentSendInset.php:639>); [connect/v1/OrderManagementPaymentWaysElectronic/SendConfirmPayment-PaymentSendConfirmUpdate.php:574](</Users/ayman/Documents/Old Mac Data/Downloads/yemensnackfood/connect/v1/OrderManagementPaymentWaysElectronic/SendConfirmPayment-PaymentSendConfirmUpdate.php:574>)
