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.
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 reconciliation
- 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, webhooks, provider actions and a payment ledger.
Operational controls
Webhook audit records, duplicate detection and reconciliation are visible to reviewers.
Safe provider switch
Mock mode proves behavior now; credentials switch each adapter to the real sandbox without changing internal business logic.
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
Every technical-team concern is now represented
“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
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 reconciliation 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 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 meeting concerns are demonstrable or explicitly assigned to Tamara provisioning. No concern is left as an undocumented assumption.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, performs full or partial capture, then supports refunds.
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 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 |
| 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: 18 August 2026. Provider documentation can change; the official go-live checklists should be re-run immediately before production approval.