Virtual IBAN
Overview
Give every customer their own IBAN, so incoming payments identify themselves. The money settles into one real account and you know instantly who paid.
Use it when you receive payments from many payers and matching them to invoices is manual work.
Virtual Accounts let you create sub-accounts under an Al Rajhi Bank Omni Collection Account. Each one gets its own IBAN and BBAN, so you can segment receivables by customer, project or business unit while all funds settle into a single physical account.
V1 is ARB-specific — bankCode is always RJHISARI. A future V2 will provide a unified multi-bank Virtual Account interface.
Prerequisites
- Authentication: Obtain an access token using the OAuth2 Client Credentials flow (see Getting Started → Authentication). Every endpoint in this product takes
Authorization: Bearer <ACCESS_TOKEN>— there are no exceptions. - Subscription: Subscribe to Virtual IBAN in your chosen environment.
A token carries only the scopes you asked for, so one issued for a different product is rejected here. Request this product's scope, or ask for several scopes in a single token as described on the Authentication page.
Concepts
- Omni Account – the physical ARB collection account holding all funds. Every VA transaction settles here. Your Omni Account IBAN is provisioned by ARB during onboarding.
- Scheme – a logical grouping of Virtual Accounts, provisioned by ARB. Each scheme maps to one Omni Account and defines the behaviour rules below. You may have one scheme or several.
- Remitter – a Virtual Account within a scheme. Each has a
remitterIdyou choose, up to 16 alphanumeric characters, plus a bank-assigned IBAN and BBAN.
CAP and non-CAP schemes
ARB provisions two types:
| Scheme type | Behaviour |
|---|---|
| CAP | The VA has a maximum. Once cumulative incoming payments reach it — in one payment or several — the VA stops accepting funds. Set maximumAmount to the contract cap. |
| Non-CAP | No restriction. The VA accepts any amount, full or partial, until blocked or expired. Set maximumAmount to a high value such as 9999999999999.99. |
maximumAmount is required for both types, and setting it to 0 means the VA cannot receive any funds at all.
Scheme resolution
With a single scheme, schemeId is optional everywhere — it is resolved automatically. With several, either pass schemeId explicitly or have a default configured during onboarding. Single-scheme customers never need to think about it.
Some behaviour is set by ARB at the scheme level and cannot be changed through the API: remitter expiry, CAP versus non-CAP mode, and the default channel configuration. Contact ARB to change those.
Channels
Channels are the payment rails, each independently enabled or disabled per VA. Both the account-level master switch and the specific channel must be enabled for a transaction to go through.
| Direction | Channel | Meaning |
|---|---|---|
| Incoming | cash | ARB branch cash deposit |
| Incoming | accountTransfer | Internal ARB account-to-account transfer |
| Incoming | cheque | Branch cheque or transfer |
| Incoming | sarie | Domestic transfers from other Saudi banks via SARIE |
| Incoming | overseas | International inbound via SWIFT |
| Incoming | eChannels | Al Rajhi digital — eBusiness portal, Mobile App, AlMubasher |
| Incoming | cdm | Cash Deposit Machines |
| Incoming | ips | ARB Instant Payment System / Mobile Mubasher |
| Outgoing | accountTransfer | Debit the VA, credit the ARB physical account |
| Outgoing | sarie | Debit the VA to a domestic bank via SARIE or IPS |
| Outgoing | overseas | Debit the VA to an international bank via SWIFT |
Sandbox test data
Two schemes are available in sandbox, shared by all test clients.
| Scheme | IBAN |
|---|---|
NeotekwithoutCAP | SA1080000012345678901007 |
NeotekCAP | SA1080000012345678901008 |
NeotekwithoutCAP is the default and resolves automatically when schemeId is omitted.
Webhooks
ARB pushes real-time notifications to a webhook URL you register during onboarding. Three event types are supported, forwarded to your URL with retry on failure:
- Bulk Payment Push – a VA bulk payment batch has completed
- Credit/Debit Notification – a real-time alert for any credit or debit on a VA
- Reconciliation – batch reconciliation data from ARB
Contact Neotek during onboarding to configure the endpoints.
Endpoints
Managing virtual accounts
| Endpoint | Does |
|---|---|
| CreateVirtualAccount | Creates one VA and returns its IBAN and BBAN |
| BulkCreateVirtualAccounts | Creates several at once with sequential ids |
| UpdateVirtualAccount | Full replacement of a VA's mutable fields |
| BlockAndUnblock | The account-level master switch |
| ChannelMaintenance | Enables or disables individual payment rails |
Reading a virtual account
| Endpoint | Does |
|---|---|
| VAStatusInquiry | Status, cap and per-channel configuration |
| VABalance | Available, clearing and blocked balances |
| VAStatement | Transaction history over a date range |
| BlockAndReleaseFunds | Reserves an amount, or returns it to available |
Paying out and reading a whole scheme
| Endpoint | Does |
|---|---|
| BulkPaymentSubmit | Sends payments out of a VA |
| BulkPaymentStatus | Where those payments got to |
| SchemeBalance | Every VA in a scheme, with totals |
| SchemeTotalBalance | Just the totals |
| ArrayBalance | Balances for a chosen set of IBANs, up to 50,000 |