# Haseb / حاسب — Kuraimi

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

Active source fallback: `https://api.kuraimipay.com:4474/alk-payments-exp/v1/PHEPaymentAPI/EPayment/`.

Active fallback labelled live; older kuraimipay.com hosts/ports are 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 |
| --- | --- | --- | --- |
| Execute payment | POST | `https://api.kuraimipay.com:4474/alk-payments-exp/v1/PHEPaymentAPI/EPayment/SendPayment` | Active PIN checkout. |
| Reverse payment | POST | `https://api.kuraimipay.com:4474/alk-payments-exp/v1/PHEPaymentAPI/EPayment/ReversePayment` | Adapter capability, not automatically invoked by every customer cancellation. |


## Configuration fields

| Field / source setting | Meaning |
| --- | --- |
| AccountUserName | Required merchant Basic-auth username. |
| AccountUserPassword | Required merchant Basic-auth password. |
| AccountUserId | Common configuration field; not sufficient to identify the customer. |
| CustomerZone / DbCustomerElectronicPaymentInfo | Required verified customer-zone metadata loaded from platform_users_electronic_payment_zone before payment. Not an arbitrary customer-controlled checkout field. |


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: Authorization: Basic base64(merchant username:merchant password). PINPASS is base64(customer PIN) in the non-local request; the local-test branch overwrites PINPASS with the raw value.

## Customer and server inputs

| Field | Requirement | Meaning |
| --- | --- | --- |
| payment_account_id | Required | Customer PIN; Flutter obscures this field. |
| code | Not the normal Haseb flow | Direct PIN payment completes during checkout; no Haseb branch exists in the generic confirmation dispatcher. |


## Payment flow

1. Validate merchant configuration, customer PIN and a verified Haseb customer-zone record. Enforce zone/currency compatibility (old/new YER IDs 3/4 in this installation).
2. Call SendPaymentAndExecutePayment, which POSTs SendPayment with customer ID, order reference, amount, YER and encoded PINPASS.
3. Provider Code=1 is treated as success and checkout sets payment_status=3.
4. There is no extra generic OTP screen for a successfully completed Haseb payment.

## Provider requests

### SendPayment

```json
{
  "SCustID": "<APPLICATION_CUSTOMER_ID>",
  "REFNO": "<ORDER_REFERENCE>",
  "AMOUNT": 1000,
  "CRCY": "YER",
  "PINPASS": "<BASE64_CUSTOMER_PIN>"
}
```

### ReversePayment

```json
{
  "SCustID": "<APPLICATION_CUSTOMER_ID>",
  "REFNO": "<SAVED_ORDER_REFERENCE>"
}
```

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

### Provider response — consumed fields

```json
{
  "Code": 1,
  "MessageDesc": "<PROVIDER_MESSAGE>",
  "Message": "<FALLBACK_MESSAGE>",
  "Date": "<PROVIDER_DATE>"
}
```

- Code must equal 1. The wrapper sets error=true for other codes, and maps MessageDesc/Message to Message.
- The source checks for the literal key "ResultSet " with a trailing space; treat that as a parser defect to review, not an official provider field.
- A direct provider success is the normal confirmed result; application/API success status=0 is a separate layer.

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

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.

A generic code-confirm endpoint exists, but the normal direct checkout for this method completes payment without an additional OTP call.

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

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

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.

- The verified-zone database record is a prerequisite; entering a PIN alone is not sufficient.
- The raw PIN overwrite is inside the localhost branch only.
- Do not assume ReversePayment is integrated with customer cancellation merely because the helper exists.

## Source evidence

- Basic auth and PIN encoding: [functions/FunctionsPaymentKuraimiHassebAcount.php:1674](</Users/ayman/Documents/Old Mac Data/Downloads/yemensnackfood/functions/FunctionsPaymentKuraimiHassebAcount.php:1674>)

- Request fields: [functions/FunctionsPaymentKuraimiHassebAcount.php:1972](</Users/ayman/Documents/Old Mac Data/Downloads/yemensnackfood/functions/FunctionsPaymentKuraimiHassebAcount.php:1972>)

- Response parsing: [functions/FunctionsPaymentKuraimiHassebAcount.php:2372](</Users/ayman/Documents/Old Mac Data/Downloads/yemensnackfood/functions/FunctionsPaymentKuraimiHassebAcount.php:2372>)

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

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

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

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

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

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