# Mastercard hosted checkout

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

Active source fallback: `https://test-gateway.mastercard.com/api/rest/version/78/merchant/<MERCHANT_ID>/`.

Active fallback is the Mastercard TEST gateway. Template placeholders {{ApiVersionNo}} and {{MerchantId}} are replaced by PaymentMasterCardApiVersionNo and AccountUserName. The commented mtf.gateway.mastercard.com alternative is not an active live configuration.

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 |
| --- | --- | --- | --- |
| Create session | POST | `https://test-gateway.mastercard.com/api/rest/version/78/merchant/<MERCHANT_ID>/session` | INITIATE_CHECKOUT. |
| Read order | GET | `https://test-gateway.mastercard.com/api/rest/version/78/merchant/<MERCHANT_ID>/order/<ORDER_REFERENCE>` | Adapter GetPayStatus helper. |


## Configuration fields

| Field / source setting | Meaning |
| --- | --- |
| AccountUserName | Merchant ID substituted into the URL and used by gateway authentication. |
| AccountUserPassword | Merchant API password. |
| PaymentMasterCardApiVersionNo | Server constant; default 78. |
| PaymentMasterCardResponseReturnUrl | Server callback/return URL template. Archive default: https://platformdgtl.com/matjari/test-cart/CheckStateOrder?orderId={{orderId}}. The route implementation was not found in the inspected archive. |
| PaymentMasterCardAccountMerchantName | Hosted-checkout merchant display name. |
| PaymentMasterCardAccountMerchantUrl | Hosted-checkout merchant URL. |
| PaymentMasterCardAccountMerchantLogoUrl | Hosted-checkout merchant logo URL. |


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." + AccountUserName + ":" + AccountUserPassword). AccountUserName is also the merchant identifier in the URL; credentials remain server-side.

## Customer and server inputs

| Field | Requirement | Meaning |
| --- | --- | --- |
| payment_id | Required | 17. |
| payment_account_id | Not a gateway card field | Backend does not require a customer wallet for method 17; archived Flutter incorrectly falls back to a generic phone field. |
| Card details | Hosted checkout intended | No supported card-field payload or completed card-entry screen was found in the inspected Flutter flow. |


## Payment flow

1. Convert/check the order amount in USD; reject orders below USD 10.
2. POST INITIATE_CHECKOUT with interaction.operation=AUTHORIZE, merchant display/return information, and order amount/currency/id.
3. Save session.id and successIndicator. Return order_session_id to the application; order remains status 2.
4. Intended next step is hosted checkout and server-side order verification. The inspected Flutter model/navigation does not consume order_session_id, and the generic confirmation dispatcher has no complete Mastercard branch. This archive does not show a complete paid-card workflow.

## Provider requests

### Create session

```json
{
  "apiOperation": "INITIATE_CHECKOUT",
  "interaction": {
    "operation": "AUTHORIZE",
    "returnUrl": "<MERCHANT_RETURN_URL_WITH_ORDER_ID>",
    "merchant": {
      "name": "<MERCHANT_DISPLAY_NAME>",
      "url": "<MERCHANT_URL>",
      "logo": "<MERCHANT_LOGO_URL>"
    },
    "displayControl": {
      "billingAddress": "HIDE",
      "customerEmail": "HIDE"
    }
  },
  "order": {
    "amount": 10,
    "currency": "USD",
    "id": "<ORDER_REFERENCE>",
    "description": "<MERCHANT_ORDER_DESCRIPTION>"
  }
}
```

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

### Gateway session — consumed fields

```json
{
  "session": {
    "id": "<SESSION_ID>"
  },
  "successIndicator": "<SUCCESS_INDICATOR>"
}
```

### Gateway failure — consumed fields

```json
{
  "error": "<GATEWAY_ERROR>",
  "explanation": "<GATEWAY_EXPLANATION>"
}
```

- Session creation requires nonempty session.id and successIndicator. It is not a capture/settlement confirmation.
- The application create response adds result.order_session_id; the adapter normalizes session values as ResponseSessionId and ResponseSuccessIndicator.
- The response parser was written mainly for session creation. A GetPayStatus helper exists but should not be treated as a proven complete order-settlement parser.

## 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": 17
}
```

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 archived app does not implement the hosted-card completion flow.

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

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

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 fallback uses test credentials/host and a test-cart return URL. This documentation does not reproduce credentials.
- Flutter does not implement the session handoff.
- AUTHORIZE is configured; session creation alone does not capture customer money.
- No confirmed production success/callback response can be established from this archive.

## Source evidence

- Session/order URLs: [functions/FunctionsPaymentMasterCardAcount.php:2579](</Users/ayman/Documents/Old Mac Data/Downloads/yemensnackfood/functions/FunctionsPaymentMasterCardAcount.php:2579>)

- Checkout request: [functions/FunctionsPaymentMasterCardAcount.php:2809](</Users/ayman/Documents/Old Mac Data/Downloads/yemensnackfood/functions/FunctionsPaymentMasterCardAcount.php:2809>)

- Session parser: [functions/FunctionsPaymentMasterCardAcount.php:3951](</Users/ayman/Documents/Old Mac Data/Downloads/yemensnackfood/functions/FunctionsPaymentMasterCardAcount.php:3951>)

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

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

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

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

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

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

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

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

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