SNB Mobile API integration services (SAMA OpenBanking)

Deliverables checklist

• OpenAPI 3.1 specification covering login, accounts, transactions, transfers, statements, savings.
• Protocol & auth flow report (TLS pinning posture, device-binding, refresh-token rotation, OTP step-up).
• Runnable source in Python or Node.js with retry, idempotency keys, and pagination helpers.
• Postman collection, integration test harness, and synthetic data fixtures.
• Compliance memo: SAMA Open Banking principles, KSA Personal Data Protection Law (PDPL) data-minimization, retention defaults.
• Operational runbook for token rotation, error codes, and IBAN-format edge cases.

Engagement options

• Source-code delivery from $300 — receive runnable client code, schemas, and docs; pay after acceptance.
• Hosted pay-per-call API — call our endpoints, pay only for what you use; ideal for variable workloads such as month-end statement pulls.
• Embedded engineer — short-term retainer for teams that need protocol analysis support during their own build.

1. ERP and accounting reconciliation

A Riyadh-based trading group with a SAP backend wants daily SAR transaction feeds for ten SNB corporate accounts. Our connector pulls statement and balance data via the Account Information channel, normalises narration fields, and posts journal entries through SAP S/4HANA's API. Maps directly to the SAMA Open Banking AIS use case.

2. Treasury dashboard for SAR/USD/AED positions

A multi-entity group with SNB Mobile (Saudi) and SNB UAE accounts needs one liquidity view. We aggregate IBAN-level balances and FX-converted USD totals, push them to a Looker dashboard, and feed exception rules (negative balance, unexpected outflow) into Slack and Microsoft Teams. The flow uses the bank's transfer status events to detect in-flight SWIFT legs.

3. Musaned payroll evidence pipeline

HR teams that pay domestic workers via SNB's Musaned service must keep auditable evidence of each transfer. Our integration captures the Musaned event (worker ID, amount, status), stores it in object storage with a hash and timestamp, and exposes a search API for labour-ministry inspections. This maps to compliance use cases under PDPL data-retention rules.

4. Fintech onboarding with consent reuse

A licensed Third-Party Provider under the SAMA Open Banking Framework wants to skip duplicate KYC. We exchange the customer consent token, fetch profile + 12-month transaction history, and produce a risk score and verified-income summary. The handover follows the framework's customer-experience guidelines for consent screens and revocation flows.

5. NEO cross-border spend analytics

Travel-tech operators using the NEO multi-currency card request a granular spend feed. Our pipeline normalises FX trades into a single ledger with merchant category, original currency, settlement currency and SNB rate, then drives traveller-by-traveller reporting and policy alerts.

Authorization & session

POST /api/v1/snb/auth/session
Content-Type: application/json
X-Idempotency-Key: 2cf1-91b3-a4d2

{
  "channel": "snb-mobile",
  "device_binding": "ed25519:pubkey...",
  "consent_id": "cnst_01HW9...",
  "scope": ["accounts:read","transactions:read","transfers:read"]
}

200 OK
{
  "session_id": "sess_01HXA...",
  "expires_at": "2026-05-08T11:42:00Z",
  "refresh_after": 1500,
  "step_up_required": false
}

Statement query (paged)

POST /api/v1/snb/statements
Authorization: Bearer <ACCESS_TOKEN>
Content-Type: application/json

{
  "iban": "SA0380000000608010167519",
  "from_date": "2026-04-01",
  "to_date":   "2026-04-30",
  "channels":  ["TRANSFER","POS","SALARY"],
  "page":      1,
  "page_size": 200
}

200 OK
{
  "page": 1,
  "total_pages": 3,
  "currency": "SAR",
  "transactions": [
    {
      "id": "txn_01HX...",
      "ts": "2026-04-03T08:14:12Z",
      "amount": -245.00,
      "channel": "POS",
      "merchant": "PANDA HYPERMARKET RIYADH",
      "narration": "POS SAR 245.00",
      "balance_after": 9821.55
    }
  ]
}

Transfer-status webhook

POST https://your-backend.example/webhooks/snb
X-Signature: t=1715168400,v1=9f2a...
Content-Type: application/json

{
  "event": "transfer.status_changed",
  "transfer_id": "trf_01HX...",
  "old_status": "PENDING",
  "new_status": "CANCELLED_BY_CUSTOMER",
  "reason_code": "USER_CANCEL",
  "occurred_at": "2026-05-08T09:11:03Z"
}

# Recommended handling:
# 1. Verify HMAC signature against rotating secret.
# 2. Idempotency by transfer_id + new_status.
# 3. Reconcile against your in-flight ledger and emit
#    a 'TRF_CANCELLED' event downstream.

Error model

Errors follow a structured envelope with code, http_status, retryable, and guidance. Common cases include CONSENT_EXPIRED (re-authorize), STEP_UP_REQUIRED (push to mobile OTP), RATE_LIMIT (back off with jitter), and IBAN_NOT_OWNED (consent scope mismatch). Each error is mapped to a SAMA-aligned remediation message your client can surface to end users.

Compliance & privacy

All SNB Mobile work runs under explicit customer authorization or documented public/regulated channels. We design every client to fit the SAMA Open Banking Policy, which has been live since the framework launch in November 2022 and is part of the Vision 2030 Financial Sector Development Program. Account Information Services (AIS) and Payment Initiation Services (PIS) are the two regulated surfaces we lean on. Data handling also aligns with the Saudi Personal Data Protection Law (PDPL) — minimization by default, retention windows declared up front, and data-subject access surfaces ready for audit.

Where customers operate cross-border, we map the same controls to GDPR, the UK FCA Open Banking model, and the UAE Central Bank's Open Finance Regulation, so a single client can serve Saudi, UAE and European deployments without behavioural drift.

Security defaults

• TLS 1.3 with certificate pinning observed at the mobile-app layer.
• Short-lived access tokens, refresh-token rotation, and device-bound keys.
• Webhook signing with rotating shared secrets and replay protection.
• Per-tenant secret isolation in HashiCorp Vault or AWS Secrets Manager.
• Structured audit log retained for the SAMA-recommended period, hash-chained for tamper evidence.

About OpenFinance Lab

We are an independent technical studio focused on mobile fintech, OpenData and OpenFinance API integration. Our team brings hands-on experience from retail banks, payment processors, mobile-protocol analysis and cloud infrastructure, and we regularly work with clients in the GCC, EU and Southeast Asia.

• Saudi National Bank, NEO, Al Rajhi, Alinma and other GCC banking integrations.
• Statement, transfer and balance APIs, plus reconciliation and exports for finance teams.
• Custom Python, Node.js and Go SDKs with test harnesses and Postman collections.
• End-to-end pipeline: protocol analysis → build → validation → SAMA / PDPL compliance review.
• Source-code delivery from $300 — receive runnable client code and full documentation; pay after delivery upon satisfaction.
• Pay-per-call hosted API — call our endpoints, pay only per call, no upfront fee; ideal for variable workloads.

Contact

Send us the target app (already SNB Mobile), the data you need, and the regions involved. We respond within one business day with scope and a fixed-price quote.

Contact page

Engagement workflow

1. Scope confirmation: target accounts (retail, corporate, NEO), data needs, region (Saudi or SNB UAE).
2. Protocol analysis and API design (2–5 business days, complexity-dependent).
3. Build and internal validation against synthetic and authorized live data (3–8 business days).
4. Documentation, sample apps, integration tests, and compliance memo (1–2 business days).
5. Typical first delivery: 5–15 business days; SAMA-related approvals or third-party sandboxes may extend timelines.

FAQ

What do you need from me to start an SNB Mobile integration?

How long does delivery take for an SNB Mobile API package?

How do you handle SAMA compliance and customer privacy?

Do you support both SNB Mobile (Saudi) and SNB UAE?