Host function
orderPayment
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.
orderPayment is a Private extended API: request it in the developer portal and register it in SGConf.js first — see Host functions. Like every extended API, it takes success / fail callbacks and answers with a result field.
Your job in orderInfo 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.
Parameters
miniappIdRequired
Your Mini App id, from ft.getAccountInfoSync().
Example
const app = getApp()
ft.orderPayment({
orderInfo: {
vendor_order_ref: '1234567orderid',
items: [ /* your items — see "Items" below */ ],
subtotal: '98.00',
delivery_fee: '10.00',
tax_amount: '0.00',
total_amount: '108.00',
currency: 'SAR',
},
idempotencyKey: 'your-idempotency-key',
miniappId: app.globalData.miniappId,
success: (res) => {
if (res.result !== 'success') {
console.log('orderPayment failed', res.message);
return;
}
if (res.status === 'already_paid') {
// paid in an earlier session — nothing left to charge
} else if (res.status === 'created') {
// the order exists, the user backed out without paying
} else {
// paid — res.status is the real status name from the backend
}
},
fail: (err) => console.log('orderPayment fail', err),
});Response
// failure
{ result: 'failure', message }
// success
{ result: 'success', status, order_id, message }status is the outcome of the payment attempt, not an order status:
'already_paid'
Paid in an earlier session — nothing left to charge
'created'
The order exists, the user backed out without paying
anything else
Paid — the real status name from the backend
order_id here is the super app's uuid, not your reference. This is the one API that returns the uuid. Your own reference goes out in orderInfo.vendor_order_ref, and that is what deep links come back on.
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.