جاري التحميل…
جاري التحميل…
Three ways to reach Flow. All three end the same way: the transaction is on your dashboard, payment.succeeded reaches your webhook, and the buyer lands on your successUrl. What differs is who draws the method picker.
| 1 · Hosted checkout | 2 · Your own checkout | 3 · SDK | |
|---|---|---|---|
| Who draws the picker | Flow, at checkoutUrl | you | Flow, inside your page or app |
| Calls | POST /sessions | GET /payment-options → POST /sessions/{token}/pay | POST /sessions + MinnhaPay.open |
| Where the card is typed | the gateway's page | the gateway's page | the gateway's page |
| Cards, BNPL, financing, instalments | yes | yes | yes |
| Card + financing split | yes | hosted page only | yes |
| Best for | the fastest launch | B2B, ERP, an existing checkout | web and mobile apps |
Create a session and send the buyer to checkoutUrl. The page asks how to pay (in full, in instalments, with financing), then with what, and shows what happens next as a numbered sequence with the figure due today before the button.
POST /api/v1/sessions
X-Api-Key: mp_test_...
{ "amount": 1000.00, "currency": "SAR", "description": "Order #123",
"successUrl": "https://yourapp.com/orders/123/success",
"cancelUrl": "https://yourapp.com/orders/123/cancel" }Two calls. The first is the menu, priced at your agreed rates on the gateway routing would pick; the second is the payment.
GET /api/v1/payment-options?amount=1000¤cy=SAR&country=SA
X-Api-Key: mp_test_...{
"amount": 1000.00, "currency": "SAR",
"options": [
{ "kind": "CARD", "code": "MADA", "gateway": "PAYTABS", "flow": "REDIRECT",
"fee": { "percent": 1.3, "fixed": 0, "amount": 13.00 },
"payer": { "dueToday": 1000.00, "total": 1000.00 } },
{ "kind": "BNPL", "code": "TABBY_INSTALLMENT", "gateway": "TABBY", "flow": "REDIRECT",
"payer": { "dueToday": 250.00, "total": 1000.00, "instalments": 4, "estimate": true },
"requires": ["customerFirstName", "customerLastName", "customerPhone"] },
{ "kind": "INSTALMENTS", "code": "PLAN", "splits": [2, 3, 4], "interestPercent": 5,
"schedules": [{ "count": 2, "dueToday": 525.00, "total": 1050.00 }],
"requires": ["customerEmail", "customerPhone", "customerNationalId"] },
{ "kind": "FINANCING", "code": "TAMWEEL_FINANCING", "gateway": "TAMWEEL_AWWAL", "flow": "HANDOFF" },
{ "kind": "SPLIT", "code": "CARD_PLUS_FINANCING", "flow": "HOSTED", "cardIsHeldNotCharged": true }
]
}The same menu for an existing session is at GET /api/v1/sessions/{token}/options. Then pay with the buyer's choice and send them to redirectUrl:
POST /api/v1/sessions/{token}/pay
X-Api-Key: mp_test_...
Idempotency-Key: 7c9e...
{ "paymentMethod": "MADA" }
→ { "status": "PROCESSING", "success": true, "gateway": "PAYTABS",
"redirectUrl": "https://secure.paytabs.sa/payment/page/...", "plan": null }A BNPL product names its provider and needs the buyer's name and mobile. To start your instalment plan, send a card scheme plus "instalments": { "count": 3, "autoPayment": true } and the payer's email, mobile and national ID; the session becomes the first instalment.409 means the session cannot be paid (paid, expired, split); success: false means the provider refused.
your server ── POST /sessions ───────────────▶ Flow session PENDING
your server ── GET /sessions/{token}/options ─▶ Flow the menu, priced
your server ── POST /sessions/{token}/pay ─────▶ Flow ─▶ gateway authorised there
your page ── redirect to redirectUrl ────────▶ gateway's page the card is typed here
gateway ─── webhook to Flow; buyer back ───────▶ Flow /complete one-second hop
Flow ─────── redirect ─────────────────────────▶ your successUrl
Flow ─────── payment.succeeded ────────────────▶ your webhook the source of truthconst menu = await minnha.paymentOptions.quote({ amount: 1000, currency: "SAR" });
const session = await minnha.sessions.create({ amount: 1000, currency: "SAR", successUrl, cancelUrl });
const paid = await minnha.sessions.pay(session.sessionToken, { paymentMethod: "MADA" });
res.redirect(paid.redirectUrl!);checkoutUrl.Every client SDK — browser (redirect, popup, embed), React, Angular, React Native, iOS, Android — opens the hosted page for a sessionToken your server created and hands back one normalised outcome. They put the page inside your product; they do not replace it. The Node SDK covers both paths: sessions.create for the hosted page, paymentOptions.quote + sessions.pay for your own.
PayTabs, HyperPay, Moyasar, Tap and Checkout.com ship card-entry SDKs: they tokenise a card, draw an Apple Pay sheet, run 3-D Secure in-app. Flow's SDKs are orchestration SDKs: which gateway, at what rate, with what failover, one webhook, one refund call, one ledger. Different layer, so:
gatewayToken on POST /sessions/{token}/pay, built per gateway the day a merchant asks.