Connect your platform to Faavo restaurants through Nexus.
Use these docs to send restaurant orders into Nexus, receive signed status events back to your system, and prepare a production integration without calling Duuliye or Faavo internal APIs directly.
ORDER #NX-4100
Westlands Kitchen → Partner gateway
Received
Mapping
Routing
Accepted
Shop mapping
Faavo maps each of your external shop IDs to the correct Faavo restaurant before live traffic starts.
API key
Every request from your platform sends the issued key in X-API-Key. Store it like a password.
Order ingest
Send new orders to one stable endpoint. Nexus normalizes common POS field names before forwarding.
Partner webhooks
Nexus signs outbound events so your platform can verify status changes and delivery notifications.
Navigation
Choose what you need
Jump straight to the part of the integration you are working on. Most teams start with sandbox credentials, then send a test order, then wire up webhooks.
Get credentials
Base URL, platform slug, API key, mapped shops, and partner OpenAPI links.
Send orders
Use one endpoint to create orders from POS, delivery, or custom ordering systems.
Receive events
Verify signed Nexus webhooks and process status updates safely.
Go live
Check production readiness before real restaurant traffic starts.
Sandbox
Use issued sandbox credentials first
Faavo will issue the platform slug, API key, webhook secret, mapped test shop IDs, and partner console access for your integration. Keep placeholders out of production traffic.
Base URL
https://api.nexus.faavo.co
Platform slug
acme-pos
API key
Issued during onboarding
Mapped shop IDs
Provided by Faavo for each test restaurant
API reference
Available to approved partners in the Nexus console
Before coding
What Faavo gives you
A partner integration starts with credentials and shop mappings. Your API key, platform slug, webhook secret, and mapped shop IDs are issued by the Faavo team.
Share company name, technical contact, webhook URL, and the Faavo shops you need connected.
Faavo creates your partner integration, maps shop IDs, and issues one API key.
Send one test order per mapped shop and confirm it appears correctly in Faavo.
Verify webhook signatures and acknowledge events with any 2xx response.
Complete go-live checks before production credentials are enabled.
Authentication
Use your partner API key
Send your API key on every order ingest request. Use the platform slug exactly as Faavo issued it; it is part of the endpoint path.
Header
X-API-Key: nexus_live_...
Path
/ingest/:platform/order
Storage
Keep production keys in a secret manager, never in client-side code.
Partner-facing endpoints
| Method | Path | Purpose | Auth |
|---|---|---|---|
| POST | /ingest/:platform/order | Create or queue a partner order | X-API-Key |
| GET | /health/ready | Check API readiness before sending traffic | Public |
Order ingest
Send orders to Nexus
External POS, delivery, marketplace, and custom ordering systems send orders to Nexus only. Nexus handles shop mapping, payload normalization, and downstream delivery to connected Faavo or Duuliye systems.
curl -X POST https://api.nexus.faavo.co/ingest/acme-pos/order \
-H "X-API-Key: nexus_live_..." \
-H "X-Order-Id: ORD-10045" \
-H "Content-Type: application/json" \
-d '{
"id": "ORD-10045",
"shop_id": "shop-westlands",
"status": "placed",
"currency": "KES",
"total": 2450,
"customer": {
"name": "Amina Hassan",
"phone": "+254700000000"
},
"items": [
{ "id": "burger-classic", "name": "Classic Burger", "quantity": 2, "price": 950 },
{ "id": "fries", "name": "Fries", "quantity": 1, "price": 550 }
],
"notes": "No onions"
}'| Field | How Nexus uses it |
|---|---|
| id or order_id | Unique order identifier from your system. Also accepted via X-Order-Id. |
| shop_id | Your external shop or restaurant ID. Must match the mapping configured in Nexus. |
| status | Initial order state. Common values like placed, pending, confirmed, ready, delivered, and cancelled are normalized. |
| total | Order total. Integers above 999 are treated as minor units; decimals are converted to cents. |
| currency | ISO currency code, default KES. |
| items | Array of order items. quantity or qty is accepted. price or unit_price is accepted. |
| customer | Optional customer object. name and phone are supported. |
| notes | Optional kitchen or delivery notes. |
Payload examples
Pick the shape closest to your platform
You do not need to match one exact schema. Nexus accepts common POS and delivery field names, then normalizes them internally.
{
"order_id": "DEL-55291",
"restaurant_id": "restaurant-44",
"order_status": "confirmed",
"currency_code": "KES",
"grand_total": 3100,
"customer_name": "Brian Otieno",
"customer_phone": "+254711111111",
"line_items": [
{ "product_id": "wrap-chicken", "product_name": "Chicken Wrap", "qty": 1, "unit_price": 1200 },
{ "product_id": "juice-mango", "product_name": "Mango Juice", "qty": 2, "unit_price": 950 }
],
"special_instructions": "Call on arrival"
}{
"_id": "DUU-90013",
"restaurantId": "duuliye-westlands",
"status_text": "accepted",
"total": 1800,
"customer": { "phone": "+254722222222" },
"products": [
{ "product_id": "101", "name": "Beef Samosa", "quantity": 3, "price": 300 },
{ "product_id": "204", "name": "Tea", "quantity": 3, "price": 300 }
]
}Webhook delivery
Receive signed events from Nexus
If your integration registers a webhook URL, Nexus sends order and notification events to your HTTPS endpoint. Verify the raw body before processing.
Headers sent by Nexus
X-Nexus-SignatureHMAC SHA-256 signatureX-Nexus-Eventevent typeX-Nexus-Deliveryunique delivery idX-Nexus-TimestampISO timestamp
{
"id": "evt_2f4b0c9a7d4f41ac",
"eventType": "order.status_changed",
"timestamp": "2026-06-09T12:40:00.000Z",
"data": {
"orderId": "ord_nexus_123",
"externalOrderId": "ORD-10045",
"status": "accepted",
"shopId": "shop-westlands"
}
}const crypto = require('crypto');
function verifyNexusWebhook(rawBody, signature, secret) {
const expected = 'sha256=' + crypto
.createHmac('sha256', secret)
.update(rawBody)
.digest('hex');
const a = Buffer.from(expected);
const b = Buffer.from(signature);
return a.length === b.length && crypto.timingSafeEqual(a, b);
}Event catalog
Webhook events your endpoint can receive
Subscribe only to the events your platform needs. Nexus includes the event type in both the JSON body and X-Nexus-Event header.
ping
Test delivery used to confirm your webhook endpoint is reachable and signature verification works.
order.created
A Faavo/Nexus order was created or linked.
order.status_changed
An order moved to a new status. Use data.externalOrderId to match your order.
order.cancelled
An order was cancelled by the restaurant, customer, or upstream platform.
Normalization
Status values Nexus understands
Use the status names natural to your system. Nexus normalizes common POS terms before sending the order to Faavo.
You send
placed, pending, received
Nexus stores
new
You send
confirmed, accepted
Nexus stores
accepted
You send
preparing, in_preparation, cooking
Nexus stores
cooking
You send
ready_for_pickup, ready
Nexus stores
ready
You send
out_for_delivery, on_the_way
Nexus stores
on_a_way
You send
delivered, completed
Nexus stores
delivered
You send
cancelled, canceled, rejected
Nexus stores
canceled
Responses
Handle responses and retries
Use stable order IDs so retries are idempotent. Network failures and 5xx responses can be retried safely with the same ID.
Accepted
The order was authenticated, stored, and queued for processing.
Invalid JSON or missing fields
Fix the body shape and resend with the same order ID.
Missing or invalid API key
Check X-API-Key and the platform slug in the URL.
Duplicate order
Treat this as idempotent success if the order was already sent.
Too many requests
Retry with exponential backoff and jitter.
Temporary Nexus error
Retry safely with the same order ID.
Debugging
What to send Faavo support
Good support tickets include the IDs needed to trace the request across Nexus queues, logs, and webhook delivery attempts.
Platform slug used in the request URL.
External order ID and X-Order-Id value.
Timestamp with timezone and the HTTP status returned by Nexus.
Request body with customer personal data redacted when possible.
Webhook X-Nexus-Delivery value for delivery issues.
Your endpoint response status/body for failed webhook deliveries.
Production
Go-live checklist
Before production traffic is enabled, confirm the integration behavior with the Faavo team using real shop mappings and test orders.
All production shop IDs are mapped in Nexus.
Your webhook endpoint uses HTTPS and returns 2xx within 15 seconds.
Webhook signature verification is enabled using the secret issued by Faavo.
Order IDs are stable and reused on retries.
Your retry policy uses backoff and does not create new order IDs for the same order.
Expected ACK
Return any 2xx response after your webhook handler accepts the event.
Retries
Nexus retries failed webhook deliveries with exponential backoff.
Support data
Send platform slug, order ID, delivery ID, and timestamp when asking Faavo to investigate.
Need machine-readable reference?
Machine-readable schemas and try-it-out tools are available inside the partner console for approved integrations. Public docs stay intentionally high-level to avoid exposing infrastructure details.