Snack Quest API

Integration reference.

Everything a partner integration needs to start a checkout, confirm payment, and receive delivery updates. All requests and responses are JSON over HTTPS.

Base URL

https://snackquests.shop

Route handlers are served from the primary domain and are reachable on every Snack Quest hostname, including this one — the api. subdomain serves this page, not a separate API origin.

Authentication

x-checkout-api-key: Required on both checkout endpoints. A shared secret issued per integration. A missing or incorrect value returns 401 unauthorized before the body is parsed.
?key= query parameter: Verifies inbound Whatchimp webhooks. Register the webhook URL with the secret already appended, or requests are rejected.
Per-business webhook secret: Daraja callbacks are verified against a secret stored on the business record, so each tenant's callbacks are independently authenticated.

Checkout

POST/api/checkout/start

Opens a checkout the moment a customer selects a product in WhatsApp. Creates or resumes the conversation and returns the bot's next reply.

Requires the x-checkout-api-key header.

Request body

Field	Type	Required	Notes
phoneNumberId	string	Yes	WhatsApp number that received the message; resolves the business.
customerPhone	string	Yes	Customer MSISDN in E.164 form.
productId	string	Yes	Catalog product the customer selected.
quantity	number	No	Must be 1 — this catalog is single-unit per checkout.
referralCode	string	No	Creator referral code, when the order came from a referral link.
creatorAttributionId	string	No	Explicit attribution override.

Responses

200Checkout started; returns conversationId, nextStep and botReply.
400Malformed JSON, missing required field, or quantity other than 1.
401Missing or incorrect x-checkout-api-key.
404No business owns that WhatsApp number, or the product does not exist.
409Product is unavailable or out of stock.

POST/api/checkout/pay

Called when the customer explicitly replies PAY. Triggers the M-Pesa STK Push for an existing checkout session.

Requires the x-checkout-api-key header.

Request body

Field	Type	Required	Notes
checkoutSessionId	string	Yes	The conversationId returned by /api/checkout/start.

Responses

200STK Push dispatched.
400Malformed JSON or missing checkoutSessionId.
401Missing or incorrect x-checkout-api-key.
404No checkout session with that id.

Webhooks

Endpoints Snack Quest exposes for providers to call. Every handler is idempotent — a provider retrying a delivery will not duplicate an order, a payout, or a refund.

Endpoint	Purpose
/api/webhooks/daraja/{businessId}	M-Pesa STK Push result callback.
/api/webhooks/daraja/{businessId}/b2c-result	B2C payout result (creator withdrawals).
/api/webhooks/daraja/{businessId}/b2c-timeout	B2C payout queue timeout.
/api/webhooks/daraja/{businessId}/reversal-result	Transaction reversal result (refunds).
/api/webhooks/daraja/{businessId}/reversal-timeout	Transaction reversal queue timeout.
/api/webhooks/jumia/{businessId}	Courier shipment status transitions.
/api/webhooks/whatchimp	Inbound WhatsApp messages. Shared across every business — the receiving phone number resolves the tenant.