Authentication

All authenticated endpoints expect a Bearer API key in the Authorization header:

Authorization: Bearer <your-api-key>

API key

Merchant integrations use one key with the pk_live_ prefix. Requests made with this key perform normal production operations: orders may charge the merchant wallet, notify delivery partners and agents, dispatch drivers, and fire webhooks.

Obtaining keys

Keys are long random strings with the live prefix:

pk_live_xxxxxxxx…

Request a key from the Wasal team or have an administrator generate it from the merchant record in the Wasal admin dashboard.

Regenerating a key invalidates the previous one. If you regenerate, update every system that uses the old key immediately or its requests will start returning 401 INVALID_API_KEY.

Security guidance

• Never expose pk_live_ keys in client-side code (browser, mobile app bundles). All production calls must originate from your server.
• Store keys in environment variables or a secrets manager — never commit them to source control.
• Do not run automated integration tests against production merchant accounts. Use demo accounts and coordinate any order lifecycle tests with operations.
• Rotate keys periodically and immediately if one is ever exposed.
• All traffic must be over HTTPS. Plain HTTP requests are rejected.

Verifying your key

The quickest way to check that a key works is the merchant profile endpoint:

curl https://www.wasal.org/api/v1/integration/merchant/profile \
  -H "Authorization: Bearer pk_live_YOUR_KEY_HERE"

GET /integration/merchant/profile

Returns your merchant record under data.merchant — name, configuration, and wallet state. A 200 confirms the key is valid and the account is active; any of the errors below tells you what's wrong.

Authentication errors

HTTP	code	Meaning
401	MISSING_API_KEY	No Authorization: Bearer header was sent.
401	INVALID_API_KEY_FORMAT	The key does not start with pk_live_.
401	INVALID_API_KEY	The key is well-formed but does not match any merchant.
403	MERCHANT_INACTIVE	The merchant account is deactivated.

See the full Error Reference.

Public endpoints (no key required)

Three endpoints are intentionally public and require no key:

• GET /integration/merchant/governorate-area — area lookup (governorates, neighborhoods, blocks…)
• GET /integration/merchant/governorate-area/civil-id — Civil ID (PACI) lookup
• GET /integration/merchant/order/track/:orderNumber — customer-facing order tracking

Everything else requires a valid Bearer key.