MANAGEMENT IMPLEMENTATION BRIEF
How the integration works—and where every requirement comes from.
A source-backed view of the customer journey, provider state machines, team responsibilities, and the boundary between what we can build independently and what each provider must enable.
9.6/10Team-share readiness
9.8/10 · Documentation fidelityRequired payloads, distinct retail endpoints, status handling, and field-level sources reviewed 25 Aug 2026.
9.7/10 · Scenario coverageOnline, SMS link, QR, approval, rejection, cancel, expiry, capture, refund, and provider-status checks are demonstrable.
External gate · not a code gapProvider credentials, merchant settings, official QA, and production activation cannot be self-issued.
01 · SOURCE-BACKED ARCHITECTURE
One internal payment model, two provider adapters
Each numbered badge opens the exact official document used to define that step.
POST-ORDER CONTROL PLANEInternal OMS / service
Security rule: the browser return URL is navigation only. The backend verifies provider state before fulfillment. Tabby states this explicitly; Tamara’s checklist requires merchant and provider states to remain synchronized. T2 M5
02 · PROVIDER STATE MACHINES
The statuses our internal adapter must normalize
The exact provider words remain in the audit trail; normalized states drive shared business logic.
Payment states [T3]
CREATED→AUTHORIZED→CLOSED
Capture: adds a capture while the payment remains authorized, then payment closes when processing completes. Exit paths: rejected, expired, close before capture, refund after capture.
Order states [M3]
new→approved→authorised→captured
Capture: signals that shipped / fulfilled value enters settlement. Exit paths: declined, expired, canceled before capture, partially or fully refunded after capture.
Provider status→Adapter mapping→Internal status
pending · approved · authorized · captured · cancelled · refunded · rejected · expired
03 · RESPONSIBILITY BOUNDARY
Who owns each part
This distinction prevents “we can build it” from being confused with “we can activate a merchant account ourselves.”
OUR TECHNICAL TEAM
Build and operate
- Shared payment model + provider adapters
- Eligibility, payload and order mapping
- Redirect and callback routes
- Authenticated, idempotent webhook intake
- Status normalization and provider-state synchronization
- Capture, cancellation and refund triggers
- Logs, monitoring and support runbook
PROVIDER-HOSTED
Customer decision flow
- Hosted checkout experience
- OTP and customer authentication
- Eligibility / risk decision
- KYC or identity checks where applicable
- Consumer installment relationship
PROVIDER / BUSINESS OWNER
Enable and approve
- Sandbox and live credentials
- Merchant codes, min/max and product setup
- Optional features and account configuration
- Official QA / go-live acceptance
- Production activation and settlement setup
04 · WHAT THE SANDBOX PROVES
Evidence, not a slide-only proposal
Unified contract
Tabby and Tamara are isolated behind the same internal create, capture, cancel, refund and retrieve operations.
Full lifecycle
The lab demonstrates checkout, return handling, authenticated-webhook design, provider actions and a payment ledger.
Operational controls
Webhook audit records, duplicate detection and provider-status checks are visible to reviewers.
Explicit evidence levels
The lab labels documented simulation separately from provider-sandbox validation and production approval.
What this does not claim
A working internal sandbox does not replace provider-issued credentials, merchant-specific settings, contractual onboarding, certification, or production approval. Those remain required even when no clarification call is needed.
05 · TAMARA MEETING COVERAGE
Technical-team concerns, with proof level shown
“Runnable” means the mock lab exercises the behavior. “Provisioned” identifies dependencies Tamara must supply.
Widgets + Public Key
Product/checkout placement preview and account-specific Public Key dependency.
M7 · WidgetsEligibility pre-check
Eligible, ineligible, and 200ms timeout-fallback branches before checkout creation.
M8 · EligibilityOTP + Nafath
Existing-customer OTP and new KSA customer’s one-time provider-hosted identity step.
M9 · KSA TestingComplete payload
Required installments, items, consumer, address, redirects, channel, locale, risk assessment and additional data.
M10 · Create CheckoutThirty-minute expiry
Visible countdown, manual accelerated test, EXPIRED status, failure return and webhook audit.
M3 · Status FlowAccount automation
Manual, auto-authorize, and auto-authorize + auto-capture account configurations.
M3 · Status FlowAll terminal webhooks
Approved, authorised, captured, canceled, refunded, expired and declined registrations.
M4 · WebhooksPull + redirect + events
Return handling, Get Order status checks and persisted webhook confirmation.
M5 · ChecklistRefunds
Full and partial refund operations with normalized statuses and audit history.
M5 · ChecklistRetail payment link
POS creates an in-store session; SMS is primary and customer email is the documented delivery backup.
M11 · In-store SessionRetail QR session
A separate in-store endpoint creates the checkout deeplink displayed as a QR code with a required device header.
M13 · In-store QRRetail status control
15-minute expiry, automatic full capture, 5–10 second polling, webhooks, void and refunds.
M12 · POS FlowSeparate accounts
Online and existing POS credential profiles with separate token/Public Key readiness.
M6 · API SetupCoverage resultAll mapped concerns are either runnable in the simulation or explicitly marked as provider-provisioned. Live behavior is not claimed until provider-sandbox tests pass.Run the scenarios →
06 · TABBY EQUIVALENT COVERAGE
The same integration concerns, mapped to Tabby’s flow
Shared capabilities use the same internal controls; provider-owned customer steps retain Tabby’s documented behavior.
Promo + checkout snippets
Product, cart and checkout placement with Public Key and merchant-code dependencies.
T7 · On-Site MessagingBackground pre-scoring
Minimal Checkout API request with created, rejected and fail-safe branches.
T2 · Checkout FlowOTP + card linking
OTP on every transaction and provider-hosted card/Apple Pay linking for new customers.
T2 · Checkout FlowComplete payload
Buyer, items, shipping, buyer history, order history, metadata, language and URLs.
T2 · Checkout FlowThirty-minute expiry
Visible countdown with cancel, reject and automatic-expiry terminal handling.
T3 · ProcessingAuthorize then capture
Backend verifies AUTHORIZED, then either calls Capture automatically or exposes the manual full/partial action.
T3 · ProcessingRedirect + pull + webhook
All three returns remain navigation signals; Get Payment and events are authoritative.
T4 · WebhooksRetail payment link
POS creates a checkout session, triggers send_hpp_link, and the customer receives the hosted page by SMS or push.
Retail status control
20-minute default expiry, five-second polling or webhooks, session cancellation, success, rejection and expiry.
T8 · Custom Payment LinksRetail auto-capture
The lab demonstrates CLOSED/captured and AUTHORIZED exception states; enabling retail auto-capture is a merchant-account setting, not a checkout request field.
T8 · Custom Payment LinksCredentials + merchant code
Public/secret keys, merchant code, webhook authentication and optional expire event.
T6 · Integration FAQCoverage resultTabby and Tamara now share the same demonstration depth while preserving their different customer and payment-state models.Run Tabby scenarios →
07 · MANAGER EVIDENCE MATRIX
Requirement → implementation → source
Use this table for review, sign-off, or vendor conversations.
| Capability | What we implement | Tabby evidence | Tamara evidence |
|---|---|---|---|
| Eligibility | Background check before displaying the method | T2 · Checkout Flow | M5 · Go-Live Checklist |
| Checkout | Create session, persist ID, redirect to hosted page | T1 · Quick Start | M1 · Quick Start |
| Retail payment link | Create POS session, deliver hosted link, verify terminal status | T8 · Custom Payment Links | M12 · POS Flow |
| Retail QR | Create dedicated QR session and display returned deeplink | T9 · POS QR | M13 · In-store QR |
| Return security | Treat redirect as UI signal; verify on backend | T2 · Checkout Flow | M5 · State sync / pull |
| Async updates | Authenticated, deduplicated webhook processor | T4 · Webhooks | M4 · Webhooks |
| Order lifecycle | Authorize, capture, cancel, refund, retrieve | T3 · Processing | M3 · Status Flow |
| Production gate | Run official cases and submit for activation | T5 · Testing Checklist | M5 · Go-Live Checklist |
08 · OFFICIAL REFERENCE LIBRARY
Primary documentation used for this screen
Official provider documentation only. Links open the original source in a new tab.
Official docsOfficial docsSource review date: 25 August 2026. Provider documentation can change; contract tests and the official go-live checklists must be re-run immediately before production approval.