Call this from your mini app when the customer taps Place order (or your equivalent). One call handles both sides of checkout: Shoppingate creates the order, shows the customer a payment sheet with all supported methods (wallet, card, Apple Pay, Tamara), and settles it — you don't need a separate payment step.
The call resolves when the customer completes payment and rejects if they cancel or the payment fails. Your job in the body is to describe the sale — what's being bought and the money — plus, if it matters for your service, a delivery address and which branch it belongs to.
Two ways to confirm the order before payment
Your backend is the source of truth for what the customer is actually buying — inventory, pricing, availability. Before Shoppingate charges anyone, we need your backend to agree. There are two supported patterns for that hand-off; both end at the payment sheet.
Option A · Pre-register via APIRecommended
Your backend tells Shoppingate about the order before the mini app fires payment.
1
Mini app
Customer taps Place order.
2
Mini app → your backend
Your mini app hits your own API to create the cart / order in your system.
3
Your backend → Shoppingate
Your backend calls Shoppingate's Create Order API, authenticated with your vendor API key, sending the same items + totals.
4
Mini app
Fires orderPayment. Shoppingate already knows the order, so the payment sheet opens immediately — no extra round-trip.
Why it's recommended: the order is locked on both sides before the customer sees payment — cleaner audit trail, safer idempotency (dedup by your vendor_order_ref), and one less network hop in the checkout tap.
Option B · Verify on demand
Shoppingate calls your backend at payment time to confirm the order.
1
Mini app
Customer taps Place order.
2
Mini app → your backend
Your mini app hits your own API to create the cart / order in your system.
3
Mini app
Fires orderPayment on the host with the items + totals.
4
Shoppingate → your backend
We call your Order Verify endpoint to confirm the order is real, priced correctly, and still valid. On ok, the payment sheet opens.
Use it when your backend already exposes a lightweight order-lookup endpoint. You control the last-mile validation without pre-committing anything on our side.
Body fields
Required
itemsRequired
The line items — what the customer is buying. The row shape depends on your category; pick your category below to see the exact shape.
subtotalRequired
Sum of item prices before delivery and tax, as a string (e.g. "98.00"). Two decimal places.
total_amountRequired
Final amount the customer pays. The platform checks subtotal + delivery_fee + tax_amount = total_amount.
Optional
delivery_feestring
Delivery charge added to reach total_amount. Omit for pickup, dine-in, or digital orders.
tax_amountstring
Tax added to reach total_amount. Omit if your prices are tax-inclusive.
currencystring
Three-letter currency code, e.g. "SAR". Defaults to your mini app's configured currency.
delivery_addressobject
Free-form JSON object with the customer's delivery address.
shop_name_en, shop_name_arstring
Bilingual branch/storefront name shown on the receipt and order card.
shop_iconURL
Icon or logo of the branch.
shop_addressobject
JSON object with the branch's own address (distinct from delivery_address).
order_typestring
Free-form label ("delivery", "pickup", "dine_in"). Some categories use it to name a sub-type — see notes above each category's example.
customer_metaobject
Free-form JSON that travels into receipts and notifications (e.g. { "customer_name": "Ali" }).
vendor_order_refstring
Your own cart or order id. Retrying the same call with the same reference returns the original order instead of creating a duplicate.
Items — pick your category
Food, Grocery, and Pharmacy share the same row shape. The order card renders product_name + product_img; modifiers is a free-form array (size, add-ons).