Search for a command to run...
A practical guide to topology, consent, testing and country adapters for UAE and Saudi financial APIs.
No comments yet. Be the first to comment.
A buyer’s evidence ladder for separating live systems, measured results and unverified clinical claims.
A practical guide to RTL semantics, mixed-direction data, accessible forms and release testing.
What 11 live procedures reveal about critical connectivity, resilience and the evidence still missing.
Passkeys remove a common phishing target, but a weak reset flow can undo the security gain. Start with recovery, then add credentials without locking users out.
Sultan Byte
20 posts
Articles addressing day-to-day development challenges
On this page
A product that connects to bank accounts in Dubai and Riyadh may offer the same feature in both places: show balances, analyse transactions or start a payment. The integration underneath is not the same.
Saudi Arabia's framework is organised around use cases, business rules, technical standards and conformance testing. The UAE has chosen a broader open-finance scope and a central API Hub that mediates connections between licensed financial institutions and third-party providers. Those choices affect topology, onboarding, consent, testing and the products a regional team can realistically ship.
This is practical technical information, not legal advice. Licensing and launch decisions should be checked with the relevant regulator and qualified counsel.
Saudi Arabia's first Open Banking Framework release focused on Account Information Services (AIS). The Saudi Central Bank, or SAMA, said in its November 2022 announcement that a second version would focus on Payment Initiation Services (PIS). SAMA's current Open Banking programme page describes a framework made up of use cases, business rules, customer-experience guidelines, API specifications, implementation requirements and operational guidelines.
The UAE boundary is wider. The CBUAE Open Finance Regulation, issued on 10 July 2025 and marked in force, covers cross-sector data sharing and transaction initiation. Mandatory entities include banks, finance companies, payment providers, stored-value facilities, exchange houses, loan-based crowdfunding companies, insurance brokers and insurers. Onboarding is phased: the regulation says the first phase includes banks, foreign-bank branches and insurance companies. The Central Bank's programme overview describes the same consent-driven direction, while Pinsent Masons' legal guide provides a useful independent reading of the scope and licensing model.
That distinction is easy to miss. A Saudi banking integration should be modelled around the released banking use cases and their rules. A UAE platform should leave room for insurance and other regulated products, even if the first release only uses current accounts. A data model built around bank_account_id alone will age badly when policies, quotations or other financial products enter the consent journey.
UAE and Saudi regulated API architecture comparison. Sources: CBUAE and SAMA; original infographic by SultanByte.
The UAE framework specifies a central API Hub, a Trust Framework and common infrastructure services. Under the regulation, institutions must provide authorised participants with access to customer data and the ability to initiate transactions, subject to express consent, authentication and secure communication.
The practical data path looks like this:
The public UAE Open Finance API catalogue makes this separation concrete. It publishes distinct interfaces for third-party providers, the API Hub and financial institutions. It also lists consent, bank data sharing, bank service initiation, confirmation of payee, insurance data sharing, insurance quotation, events and webhooks. The site identifies OpenAPI YAML in its repository as the source of truth and showed v2.1 when checked for this article. It also states that it is a community project rather than an official CBUAE publication, so teams should reconcile implementation details with the regulation and programme notices.
Saudi Arabia's public material puts more emphasis on a common framework plus an Open Banking Lab. SAMA says the Lab provides simulated bank APIs, conformance suites and certification tooling. Banks and fintechs implement against the framework and prove conformance in the testing environment.
For engineers, this creates a useful mental model: the UAE integration has a hub as an explicit runtime dependency, while the Saudi integration is defined by common standards and certification across participating banks and fintechs. Do not hide that difference behind one generic "GCC connector".
The product layer can be shared. The regulatory and transport layers should not be.
Use a canonical internal model for customers, accounts, balances, transactions, beneficiaries, payment intents and consent. Put a country adapter between that model and each regulated ecosystem. The adapter should own endpoint discovery, local identifiers, scopes, signing, certificate handling, error translation and webhook verification.
A clean boundary might expose operations such as:
createConsent(request) -> consent
startAuthorization(consent) -> redirect
exchangeAuthorization(result) -> grant
listAccounts(grant) -> accounts
listTransactions(grant, account, cursor) -> page
createPayment(grant, instruction) -> payment
getPaymentStatus(payment) -> status
revokeConsent(consent) -> result
Those names are intentionally boring. Country-specific behaviour belongs below them. The UAE adapter can resolve Hub routes and institution capabilities. The Saudi adapter can map the same product action to the applicable SAMA use case and participating bank implementation.
Keep raw payloads as evidence, but do not let them leak through the product API. Store the original response encrypted with a short retention policy, then map it to a versioned canonical schema. This gives operations teams enough material to investigate disputes without coupling every downstream service to a regulator's field names.
Both regimes put the customer in control of data sharing. The CBUAE regulation requires express consent and sets detailed consent obligations. SAMA describes secure customer-authorised sharing and includes customer-experience guidelines in its technical standards.
Model consent as a state machine with at least requested, awaiting authorisation, active, rejected, expired, revoked and failed states. Store:
Do not interpret a valid access token as proof that consent remains usable. A customer may revoke access, an institution may reject a request, a certificate may expire or a framework rule may impose a shorter lifetime. Check consent state at the boundary and make revocation idempotent.
Payment initiation needs a separate operational record. A timeout after submission does not prove failure. Use an idempotency key, persist the provider's payment identifier before retrying, and query status. Replaying a timed-out payment as a new instruction is how an integration bug becomes a duplicate debit.
SAMA's Lab offers a simulation environment and conformance testing. Treat its tests as an early engineering input rather than the final release gate. Build the adapter against fixtures, add contract tests from the specification, then run the same scenarios against the Lab. Keep a trace from each supported use case to the relevant automated test and certification result.
The UAE catalogue says its specifications follow a vMAJOR.MINOR scheme and may publish targeted errata that supersede a base version. Pin the exact specification version used to generate clients. A build should fail when an unreviewed schema change alters a request, response or security definition. "Latest" is convenient in a documentation browser and dangerous in a production build.
Contract tests should cover more than happy paths. Include expired consent, revoked consent, unavailable institution, malformed signature, clock skew, duplicate payment submission, delayed webhook, webhook replay, pagination changes and a response containing an unknown enum value. Financial integrations fail at boundaries and during recovery, not only when a JSON field is missing.
Begin with one narrow use case in one country. Account aggregation is usually easier to reason about than payment initiation because it does not move money, though it still carries privacy and licensing obligations. Choose a real target institution and confirm that the required API and onboarding route are available before promising a launch date.
Next, build the canonical consent and account models with a country adapter. Add an immutable audit stream for authorisation events, access, revocation and payment-status changes. Keep secrets and signing keys in a managed key service, isolate certificate rotation from application releases, and verify every webhook signature before processing its body.
Only then add the second market. Reuse product screens and internal domain services where the customer experience is genuinely common. Keep local disclosures, consent wording, certification evidence, error mappings and operating procedures inside the country package.
For vendor selection, ask for live evidence rather than a coverage map. A useful due-diligence pack contains the provider's licence or regulatory status, supported institutions and use cases, production-versus-sandbox status, API-version policy, certificate model, consent and revocation behaviour, webhook guarantees, incident process, data-hosting locations, subcontractors and exit support. Vendor statements about reach should be verified against regulator records and a test connection.
Choose the UAE first when the product roadmap depends on a broader financial-data model, especially one that may combine banking and insurance, and the required institutions are available in the relevant onboarding phase. Design around the central Hub and treat its availability, identifiers and routing behaviour as part of the runtime architecture.
Choose Saudi Arabia first when the initial product maps cleanly to a released SAMA banking use case and the team can use the Lab and conformance process to drive delivery. Treat the framework's business rules and customer-experience requirements as product inputs, not documentation to read after the API client works.
A two-country launch should not be two unrelated codebases. It should be one product domain with two explicit regulatory adapters. That costs a little more at the start. It is still cheaper than discovering, during certification, that a supposedly universal connector buried consent, routing and error assumptions throughout the application.
Cover and infographic: original SultanByte visuals. The comparison is based on CBUAE and SAMA materials, with the implementation references linked in the article.