Akwaan Express — Merchant B2B Integration Guide

Audience: External merchant engineering teams. Status: Production. Version: v1.3 Last updated: 2026-05.

1. Introduction

The Akwaan Express B2B Integration lets merchants:

• Push orders into Akwaan Express via REST API.
• Receive lifecycle status updates for those orders via outbound webhooks.
• Query merchant wallet balances and submit withdraw requests.

Integration is bidirectional:

Supported capabilities

• Order creation
• Merchant profile updates
• Wallet balance retrieval
• Withdraw request submission
• Real-time order status webhooks (20 broadcastable statuses)
• OTP delivery webhooks (when an order requires customer OTP verification)

2. Architecture overview

+---------------------+         +---------------------------+
|  Merchant System    |  REST   |  Akwaan Express Backend   |
|                     +-------->+  /api/merchant/b2b/...    |
|                     |         |                           |
|  Webhook Listener   |<--------+  IntegrationService       |
|  (your URL)         |  POST   |  BroadcastOrderDetailsBulk|
+---------------------+         +---------------------------+

• All REST calls are merchant-initiated and authenticated with a static API Key sent in the ApiKey HTTP header.
• All webhooks are Akwaan-initiated and POSTed to the merchant's configured base URL with the path /api/akwaan/order-delivery/webhook appended.
• Webhook authentication is configured per merchant: a single custom header key:value pair (e.g. X-Webhook-Token: <secret>).

3. Authentication

3.1 API Key

All requests to /api/merchant/b2b/* MUST include:

The API key is mapped to exactly one merchant. The backend uses it both to authenticate the caller and to scope the request to that merchant's data. Merchants cannot read or modify another merchant's resources.

3.2 Example

POST /api/merchant/b2b/order HTTP/1.1
Host: api.akwanexpress.com
Content-Type: application/json
ApiKey: akx_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

{ ... order body ... }

3.3 Failure modes

Security note: API keys are treated as bearer credentials. Treat them like passwords — never log them, never commit them, rotate on suspected leak. Contact Akwaan operations to issue a replacement and revoke the old key.

3.4 Recommended client hygiene

• Store the key in a secrets manager (AWS Secrets Manager / Azure Key Vault / Vault / Doppler) — never in source control.
• Restrict network egress: only your backend service should be calling Akwaan, never the browser.
• Rotate the key on any suspected leak or staff offboarding.
• Use a dedicated key per environment (sandbox vs. production).

4. Outbound webhook integration

4.1 Configuration

Provide Akwaan operations with:

4.2 Lifecycle

1. An order's status changes inside Akwaan (e.g. delegate marks Delivered).
2. The status transition triggers IntegrationService.BroadcastOrderDetailsBulk.
3. Events are batched by merchant — each merchant receives one HTTP POST carrying all the events that concern them.
4. Events for non-broadcastable statuses are silently dropped (see §5).
5. The HTTP POST is dispatched with up to 3 attempts, 15s timeout per attempt, linear backoff (2s, 4s).
6. A 2xx response = delivered. A 4xx response (except 408/429) = abandoned (your error, no point retrying). A 5xx / network error / timeout = retried up to the limit.

4.3 Retry behavior

After 3 failed attempts the event is abandoned. There is no built-in catch-up mechanism today; if you suspect missed events, contact operations to schedule a replay or use the manual GET /api/merchant/b2b/order/{externalId} lookup (see §14 for a future bulk sync endpoint suggestion).

4.4 Timing & ordering guarantees

• At-least-once delivery: a webhook may arrive more than once if a retry crosses with a slow ACK on your side. Idempotent handlers are required.
• No strict ordering: webhooks are dispatched concurrently across merchants and across orders. Use the eventTimestamp field (UTC) and your stored status timestamp to decide whether to apply a state transition.
• Best-effort: webhook delivery is fire-and-forget from Akwaan's order processing — a slow or down merchant cannot block order operations. Make your endpoint return 2xx in under a few seconds and queue work asynchronously.

4.5 Webhook security

• Verify the AuthorizationKey: AuthorizationValue pair on every inbound request.
• Reject any request that does not match. Return 401.
• Restrict your webhook endpoint to Akwaan's egress IPs if you require defense-in-depth (contact operations for the current list).
• Treat the payload as untrusted until the auth header is verified.

5. Broadcasted order statuses

Akwaan broadcasts webhooks only for the 20 statuses below. Any other internal status transition does NOT generate a webhook.

Stability contract:

• The numeric status value and statusKey string are stable identifiers — branch your business logic on these.
• The statusNameEn / statusNameAr are display strings — use them for UI/email/log output only. They may be reworded without notice.
• New broadcastable statuses may be added in future releases — your handler must tolerate unknown statuses gracefully (log and ignore is fine).

6. Webhook payload structure

6.1 Top-level shape

The webhook body is a JSON array of events. One HTTP POST may contain multiple events when they concern the same merchant.

[
  {
    "EventType": "OrderStatusUpdated",
    "EventData": { ... }
  },
  {
    "EventType": "OTPSend",
    "EventData": { ... }
  }
]

6.2 EventData for OrderStatusCreated / OrderStatusUpdated

{
  "orderId": "MERCHANT-EXTERNAL-ID-123",
  "status": 10,
  "statusKey": "Delivered",
  "statusNameEn": "Delivered",
  "statusNameAr": "تم التسليم",
  "eventTimestamp": "2026-05-20T13:42:11.4321Z"
}

6.3 EventData for OTPSend

Same shape as the status events, plus an otp field:

{
  "orderId": "MERCHANT-EXTERNAL-ID-123",
  "status": 8,
  "statusKey": "InDeliveryProgress",
  "statusNameEn": "In Delivery Progress",
  "statusNameAr": "جاري التسليم",
  "eventTimestamp": "2026-05-20T13:42:11.4321Z",
  "otp": "4821"
}

6.4 EventData for OTPResend

The resend event carries only the OTP and order id (no status, since the order's status has not changed):

{
  "orderId": "MERCHANT-EXTERNAL-ID-123",
  "otp": "4821",
  "eventTimestamp": "2026-05-20T13:42:11.4321Z"
}

6.5 Required webhook response

Akwaan considers the delivery successful if your endpoint returns:

• HTTP status 200, 201, 202, or 204.
• Within 15 seconds.

The response body is ignored. Return 200 OK with an empty body as the conventional ack.

7. Inbound REST API endpoints

Base path: /api/merchant/b2b

7.1 GET /wallets

Returns the merchant's wallet balances.

7.2 POST /order

Create a new order in Akwaan.

Request body — OrderCreationIntegrationForm:

Response: ExternalOrderDto containing the order's Akwaan id, code, status, and echo of submitted fields.

7.3 PUT /merchant

Update merchant profile.

7.4 POST /withdraw-request

Submit a withdraw request against the merchant's wallet.

7.5 GET /order/{externalId}

Retrieve one of your own orders by the ExternalId you supplied when creating it. Returns every field you originally submitted plus the order's current status and full status history.

Request:

GET /api/merchant/b2b/order/MERCHANT-EXTERNAL-ID-123 HTTP/1.1
Host: api.akwanexpress.com
ApiKey: akx_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Path parameters:

Authorization & scope:

• Requires the standard ApiKey header.
• Strictly scoped to the calling merchant — the server filters by MerchantId == callerMerchantId. A merchant cannot retrieve another merchant's order even by guessing its ExternalId.
• Returns 404 Order not found for unknown ids and for ids that exist but belong to a different merchant.

Response shape — B2BOrderDetailDto:

statusHistory[] entry shape:

{
  "fromStatus": 0,
  "fromStatusKey": "Pending",
  "fromStatusNameEn": "Pending",
  "fromStatusNameAr": "قيد الانتظار",
  "toStatus": 1,
  "toStatusKey": "InPickUpShipment",
  "toStatusNameEn": "In Pickup Shipment",
  "toStatusNameAr": "في قائمة الاستلام",
  "changedAt": "2026-05-20T11:00:00.123Z",
  "shipmentCode": "SHP-2026-0042",
  "note": null
}

Sample successful response:

{
  "code": 200,
  "message": "Operation successful",
  "data": {
    "id": "8a7b6c5d-1234-5678-9abc-def012345678",
    "code": "SHOP-9912",
    "pin": "4821",
    "customerId": "CUST-7700",
    "customerName": "Ahmed Ali",
    "customerPhoneNumber": "07701234567",
    "externalId": "MERCHANT-EXTERNAL-ID-123",
    "content": "Mobile phone case",
    "pickupZoneName": "Mansour",
    "deliveryZoneName": "Karrada",
    "pickupGovernorate": { "id": 1, "name": "Baghdad" },
    "deliveryGovernorate": { "id": 1, "name": "Baghdad" },
    "amount": 25000,
    "paidAmount": 0,
    "totalAmount": 28000,
    "isPaid": false,
    "size": "Small",
    "status": 10,
    "statusKey": "Delivered",
    "statusNameEn": "Delivered",
    "statusNameAr": "تم التسليم",
    "creationDate": "2026-05-20T10:55:00.123Z",
    "lastUpdateDate": "2026-05-20T13:42:11.432Z",
    "statusHistory": [
      {
        "fromStatus": 0, "fromStatusKey": "Pending",
        "toStatus":   1, "toStatusKey":   "InPickUpShipment",
        "changedAt": "2026-05-20T11:00:00.000Z",
        "shipmentCode": "PCK-0042"
      },
      {
        "fromStatus": 1, "fromStatusKey": "InPickUpShipment",
        "toStatus":   4, "toStatusKey":   "Received",
        "changedAt": "2026-05-20T11:45:12.000Z",
        "shipmentCode": "PCK-0042"
      },
      {
        "fromStatus": 8, "fromStatusKey": "InDeliveryProgress",
        "toStatus":  10, "toStatusKey":   "Delivered",
        "changedAt": "2026-05-20T13:42:11.000Z",
        "shipmentCode": "DLV-0091"
      }
    ]
  }
}

Error responses:

8. Reference data lookups (governorates & zones)

These read-only endpoints expose the system-wide reference data merchants need to populate PickUpGovernorateId / DeliveryGovernorateId / PickupZoneName / DeliveryZoneName when creating orders. The data is identical for every merchant and updated by Akwaan operations whenever new coverage is added.

Both endpoints:

• Are public — no ApiKey header required. (Merchants typically need this data during onboarding, before an ApiKey is issued.)
• Support pagination via pageNumber and pageSize query params (defaults provided by the API).
• Return the paginated Response<T> envelope.

§1 GET /governorates

Paginated list of all governorates.

Response data shape:

{
  "code": 200,
  "message": "Operation successful",
  "data": [
    { "id": 1, "name": "Baghdad" },
    { "id": 2, "name": "Basra" },
    { "id": 3, "name": "Erbil" }
  ],
  "pagination": {
    "currentPage": 1,
    "pageSize": 20,
    "totalItems": 18,
    "totalPages": 1
  }
}

The id values returned here are the same integers you pass as PickUpGovernorateId / DeliveryGovernorateId on order creation.

§2 GET /zones

Paginated list of zones (also called districts). Filter by governorate to narrow the list.

Response data shape:

{
  "code": 200,
  "message": "Operation successful",
  "data": [
    {
      "id": 12,
      "name": "Karrada",
      "governorate": { "id": 1, "name": "Baghdad" }
    },
    {
      "id": 13,
      "name": "Mansour",
      "governorate": { "id": 1, "name": "Baghdad" }
    }
  ],
  "pagination": {
    "currentPage": 1,
    "pageSize": 20,
    "totalItems": 47,
    "totalPages": 3
  }
}

The name string is what you should send as PickupZoneName / DeliveryZoneName on order creation. Zone names are unique within a governorate; match them exactly (including casing and Arabic characters) when populating the order form.

§3 Recommended usage pattern

1. Cache GET /governorates at the start of each session — the list is short and rarely changes.
2. For each pickup/delivery selection, call GET /zones?governorateId=<id> to get the available zones for that governorate.
3. Persist the resolved governorateId and the verbatim zone name on your side keyed by your own internal region IDs.
4. Re-fetch on a low cadence (e.g. once per day) to pick up new zones as Akwaan expands coverage.

Why zone names instead of zone IDs on order creation? Historical compatibility with legacy merchant integrations. New integrations are welcome to ignore the id field and only carry the name on their side — the order endpoint resolves the name + governorate id back to a zone server-side.

§4 Example calls

GET /api/merchant/b2b/governorates HTTP/1.1
Host: api.akwanexpress.com

GET /api/merchant/b2b/zones?governorateId=1&pageSize=100 HTTP/1.1
Host: api.akwanexpress.com

9. Request / response examples

9.1 Create order — success

Request:

POST /api/merchant/b2b/order HTTP/1.1
ApiKey: akx_live_xxx
Content-Type: application/json

{
  "Code": "SHOP-9912",
  "ExternalId": "MERCHANT-EXTERNAL-ID-123",
  "CustomerName": "Ahmed Ali",
  "CustomerPhoneNumber": "07701234567",
  "Content": "Mobile phone case",
  "DeliveryZoneName": "Karrada",
  "PickupZoneName": "Mansour",
  "PickUpGovernorateId": 1,
  "DeliveryGovernorateId": 1,
  "Amount": 25000,
  "Size": "Small"
}

Response — 200 OK:

{
  "code": 200,
  "message": "Operation successful",
  "data": {
    "id": "8a7b6c5d-1234-5678-9abc-def012345678",
    "code": "SHOP-9912",
    "customerName": "Ahmed Ali",
    "customerPhoneNumber": "07701234567",
    "externalId": "MERCHANT-EXTERNAL-ID-123",
    "amount": 25000,
    "status": "Pending"
  }
}

9.2 Create order — validation error

{
  "code": 400,
  "message": "Delivery Zone or Pickup Zone cant be null or empty",
  "errors": null
}

9.3 Authentication failure

POST /api/merchant/b2b/order HTTP/1.1
Content-Type: application/json
(no ApiKey header)

{
  "code": 400,
  "message": "API Key is missing"
}

9.4 Webhook — single OrderStatusUpdated event

POST /api/akwaan/order-delivery/webhook HTTP/1.1
Host: api.your-shop.com
Content-Type: application/json; charset=utf-8
X-Webhook-Secret: <your-configured-shared-secret>

[
  {
    "EventType": "OrderStatusUpdated",
    "EventData": {
      "orderId": "MERCHANT-EXTERNAL-ID-123",
      "status": 10,
      "statusKey": "Delivered",
      "statusNameEn": "Delivered",
      "statusNameAr": "تم التسليم",
      "eventTimestamp": "2026-05-20T13:42:11.4321Z"
    }
  }
]

9.5 Webhook — mixed batch (status + OTP)

[
  {
    "EventType": "OrderStatusUpdated",
    "EventData": {
      "orderId": "MERCHANT-EXTERNAL-ID-100",
      "status": 8,
      "statusKey": "InDeliveryProgress",
      "statusNameEn": "In Delivery Progress",
      "statusNameAr": "جاري التسليم",
      "eventTimestamp": "2026-05-20T13:42:11.4321Z"
    }
  },
  {
    "EventType": "OTPSend",
    "EventData": {
      "orderId": "MERCHANT-EXTERNAL-ID-100",
      "status": 8,
      "statusKey": "InDeliveryProgress",
      "statusNameEn": "In Delivery Progress",
      "statusNameAr": "جاري التسليم",
      "eventTimestamp": "2026-05-20T13:42:11.5023Z",
      "otp": "4821"
    }
  }
]

10. Error handling

10.1 Response envelope

All API responses use the standard envelope:

{
  "code": 200,
  "message": "Operation successful",
  "data": { ... },
  "pagination": { ... },
  "errors": [ ... ]
}

10.2 Common error codes

10.3 Webhook receiver error handling on your side

• Respond 2xx fast even if you queue the work async. Treat the webhook handler like a message receiver, not a processor.
• Be idempotent: dedupe on orderId + statusKey + eventTimestamp.
• Tolerate unknown statusKey values — log and skip.

11. Security best practices

API key protection

• Store in a secrets manager, never in code or git history.
• Different key per environment (sandbox / production).
• Rotate on suspected leak or staff turnover. Contact ops to issue a new key and revoke the old one.

Webhook validation

• Always verify the configured AuthorizationKey: AuthorizationValue header on every inbound webhook.
• Restrict your webhook endpoint to known egress IPs if your security model requires it.
• Use HTTPS only.

Replay protection

• Use the eventTimestamp and your stored last-seen timestamp per order to drop stale events.
• Reject events older than your tolerance window (recommend 24h).

Timeout / availability

• Webhook handler must reply within 15 seconds. Queue heavy work, don't process inline.
• Build your handler to survive an Akwaan-side burst (status sweeps can fan-out 100s of events).

Recommended rate limits on your endpoint

• Allow at least 100 req/s sustained from Akwaan to absorb manifest-level transitions.

12. End-to-end integration flow

1. Onboarding
   ├─ Akwaan issues ApiKey + records your webhook URL & auth header
   └─ You whitelist Akwaan in your firewall (optional)

2. Order creation
   ├─ POST /api/merchant/b2b/order  ──→  Akwaan creates order
   └─ Akwaan webhook: OrderStatusCreated (status=0, Pending)

3. Lifecycle
   ├─ Delegate picks up         → webhook: Received (4)
   ├─ Arrives at warehouse      → webhook: InWarehouse (6)
   ├─ Loaded for delivery       → webhook: InDeliveryShipment (7)
   ├─ Out for delivery          → webhook: InDeliveryProgress (8)
   ├─ OTP sent (if applicable)  → webhook: OTPSend
   └─ Delivered                 → webhook: Delivered (10)

4. Settlement
   ├─ Money reconciled          → webhook: Completed (13)
   └─ Wallet balance updated   ← GET /api/merchant/b2b/wallets

5. Refund path (if needed)
   ├─ Failed delivery           → webhook: RescheduledInWarehouse (14) etc.
   ├─ Refund manifest           → webhook: InRefundShipment (27)
   └─ Returned to merchant      → webhook: RefundedToMerchant (29)

6. Error recovery
   ├─ Missed webhook?           → GET /api/merchant/b2b/order/{externalId} (manual lookup)
   └─ Suspect downtime?         → contact operations for replay

13. Testing recommendations

Sandbox

Request a sandbox API key + a sandbox webhook URL from Akwaan operations. The sandbox mirrors production schemas but uses isolated data.

Webhook receiver testing

1. Stand up a temporary webhook receiver locally:
   • ngrok or webhook.site make this trivial.
   • Configure the public URL with Akwaan as your sandbox webhook URL.
2. Create test orders via POST /api/merchant/b2b/order.
3. Trigger status transitions (Akwaan ops can step a sandbox order through the lifecycle).
4. Verify your handler:
   • Authenticates the header.
   • Parses every payload shape.
   • Is idempotent (replay the same event and assert no double-write).
   • Returns 2xx within 15s.
5. Failure cases to exercise:
   • Your endpoint returns 500 → Akwaan retries up to 3 times.
   • Your endpoint takes 30s → first attempt times out, retry.
   • Your endpoint returns 401 → no retry (assumed permanent).

Load testing

In sandbox, ask operations to bulk-transition 1000+ orders. Verify your endpoint sustains the burst.

14. Edge cases & expected behavior

15. Versioning & changelog

This document describes integration version v1.

Breaking changes (renamed fields, changed semantics of existing values, removed statuses) will be announced via email and a new major version (v2). Additive changes (new fields, new broadcastable statuses) will be released in minor version notes — your handler should already tolerate them.

Changelog

For credential issuance, integration support, or to report a webhook delivery issue, contact Akwaan operations.