Alinma Pay API integration services (SAMA OpenFinance)

Wallet transaction history API

Pulls the full Alinma Pay activity ledger the user sees in-app: merchant purchases, SADAD billers, top-ups from linked mada cards, SARIE transfers, and cross-border Alinma Express remittances. Supports cursor-based paging, date windows, and channel filters — the foundation for reconciliation, spend analytics, and audit trails.

Statement & export service

Monthly statement generation with exportable JSON, CSV, Excel (.xlsx), and PDF. Fields include transaction reference, SARIE IPS ID when available, MCC, biller ID for SADAD, FX rate for international transfers, and settlement timestamp. Ideal for accounting integrations and VAT returns under ZATCA.

Card issuance & tokenization events

Capture digital card lifecycle: instant mada/Visa issuance, Apple Pay & mada Pay token provisioning, activation, freeze/unfreeze, and CVC rotation. Use for fraud signaling, customer-service dashboards, or enterprise card-fleet visibility.

Transfer & remittance webhook

Real-time webhook stream for outbound SARIE transfers and Alinma Express corridor payments. Event payloads carry status (initiated, cleared, rejected), correspondent bank data, and compliance flags — so your AML engine, remittance CRM, or treasury system stays in sync without polling.

Bill payment & split-bill integration

Structured access to SADAD bill payment history (utilities, telcos, government services) plus the peer-to-peer split-bill requests that Alinma Pay users create with family and friends. Use cases: group-expense apps, household finance tools, SME payroll utilities.

Authentication & session bridge

Implements an authorization bridge that respects SAMA Open Banking explicit customer consent: short-lived access tokens, refresh tokens, device binding, biometric step-up, and consent revocation endpoints. Consent scopes are granular (accounts.read, payments.initiate, statements.export).

1. Authorization & token exchange

// Step 1: Obtain consent-backed access token (OAuth-style)
POST /api/v1/alinma-pay/auth/token
Content-Type: application/json

{
  "grant_type": "user_consent",
  "consent_id": "cst_8a7c41...",
  "client_id": "studio_xyz",
  "client_secret": "****",
  "scope": "accounts.read statements.read transfers.read"
}

// 200 OK
{
  "access_token": "eyJhbGciOi...",
  "token_type": "Bearer",
  "expires_in": 900,
  "refresh_token": "rft_9d3f...",
  "consent_expires_at": "2026-07-20T00:00:00Z"
}

2. Fetch wallet statement

POST /api/v1/alinma-pay/statement
Authorization: Bearer <ACCESS_TOKEN>
Content-Type: application/json

{
  "wallet_id": "wlt_ksa_0192",
  "from_date": "2026-02-01",
  "to_date":   "2026-02-28",
  "channels":  ["MERCHANT","SADAD","SARIE","ALINMA_EXPRESS","P2P"],
  "format":    "json"
}

// 200 OK — truncated
{
  "wallet_id": "wlt_ksa_0192",
  "currency": "SAR",
  "opening_balance": 1240.55,
  "closing_balance": 865.20,
  "count": 48,
  "items": [
    {
      "id": "txn_01HT...",
      "ts": "2026-02-03T09:12:44+03:00",
      "amount": -129.00,
      "channel": "MERCHANT",
      "mcc": "5411",
      "merchant": "Panda Supermarket",
      "card_token": "mda_tkn_7a9...",
      "reference": "MDA20260203091244"
    }
  ]
}

3. Webhook: transfer status

POST https://your-app.example.com/hooks/alinma-pay
X-Signature: t=1739000000,v1=9a8b...
Content-Type: application/json

{
  "event": "transfer.cleared",
  "sent_at": "2026-02-15T14:01:09+03:00",
  "data": {
    "transfer_id": "trf_41c0...",
    "type": "SARIE_IPS",
    "amount": 2500.00,
    "currency": "SAR",
    "beneficiary": {
      "iban": "SA03 8000 0000 6080 1016 7519",
      "bank": "Al Rajhi Bank"
    },
    "status": "cleared",
    "fees": 0.00
  }
}

// Error handling: verify X-Signature with your webhook
// secret; retry policy is 5x with exponential backoff.

4. List digital card tokens

GET /api/v1/alinma-pay/cards?wallet_id=wlt_ksa_0192
Authorization: Bearer <ACCESS_TOKEN>

// 200 OK
{
  "cards": [
    {
      "card_id": "crd_01HV...",
      "scheme": "mada",
      "state": "active",
      "tokens": [
        {"wallet": "apple_pay",  "token_state": "provisioned"},
        {"wallet": "mada_pay",   "token_state": "provisioned"}
      ],
      "issued_at": "2025-11-02T10:14:00+03:00"
    }
  ]
}

Saudi regulatory alignment

Alinma Pay is supervised by SAMA (Saudi Central Bank). Every integration we deliver is framed against:

• SAMA Rules for Electronic Wallets (issued October 2024, effective 90 days from publication) — our consent, KYC-tier, and limits model follows the wallet account categories defined there.
• SAMA Open Banking Framework (Second Release) — AIS / PIS-style scopes, explicit consent, and revocation endpoints are implemented by default.
• Law of Payments and Payment Services (Royal Decree No. M/26) and its implementing regulations — the legal basis under which wallets operate in the Kingdom.
• Personal Data Protection Law (PDPL) of Saudi Arabia — data minimization, purpose limitation, and retention schedules applied to every field exposed by the API.

Operational controls

• Explicit, per-scope consent records stored immutably for audit.
• Short-lived tokens (≤15 minutes) with refresh rotation and device binding.
• TLS 1.2+ everywhere; mTLS available for enterprise clients.
• PII pseudonymization and hashed counterparty identifiers on export.
• Signed webhooks (HMAC-SHA256) with replay protection.
• No credential storage; authorization uses the customer's authenticated session, not stored passwords.

About our studio

We are an independent technical studio specializing in App interface integration and authorized API implementation for global clients. Our engineers come from banks, payment processors, protocol-analysis teams, and cloud infrastructure providers, with many years of hands-on fintech experience across MENA, South Asia, and Europe.

• End-to-end: protocol analysis → API design → build → validation → compliance sign-off.
• Deep familiarity with SAMA Open Banking, UAE CBUAE Open Finance, PSD2, and India UPI.
• Custom SDKs in Python, Node.js, Go, and Java with full test harnesses.
• Android and iOS coverage — including reverse engineering of client traffic with full documentation.
• Source code delivery from $300 — you receive runnable API source code, OpenAPI specs, and a full delivery report; payment after you validate the deliverable.
• Pay-per-call hosted API — zero upfront cost; use our managed endpoints and pay only for successful calls.

Contact

To request a quote, scope a new Alinma Pay integration, or book a free consultation, open our contact page and share your target data (transactions, cards, transfers, bill payments) plus any sandbox credentials you already hold.

Open contact page

Typical response time: under one business day (Riyadh / UTC+3).

Engagement workflow

1. Scope confirmation (day 0–1): you share the exact Alinma Pay data needed — transactions, statements, transfers, card events — plus region and compliance constraints.
2. Protocol analysis & API design (2–5 business days): we map the target flows, draft the OpenAPI spec, and confirm data fields with you.
3. Build & internal validation (3–8 business days): implementation, sandbox testing, and traffic capture against realistic scenarios.
4. Docs, samples & test cases (1–2 business days): Postman collection, curl examples, and language-specific SDK snippets.
5. First delivery window: typically 5–15 business days; banking/regulator approvals may extend timelines for production endpoints.

FAQ

What do you need from me to start?

How long does delivery take?

How do you handle compliance?

Do you cover other KSA wallets?