Create new virtual account

Create a unique virtual account linked to a primary account to receive and identify payments. The API returns the virtual account number and Virtual IBAN upon successful creation.

Important information

The user must provide the valid credentials in the header
Encrypted and valid Signature and an active "Access Token"
Request format as specified with all the mandatory details with appropriate request tags

Domain details
Environment
Domain
Rate/Limit
Sandbox
sandboxapi.onesingleview.com
3 Calls per Minute
Production/LIVE
To be provided upon onboarding
Based on contract

Environment	Domain	Rate/Limit
Sandbox	sandboxapi.onesingleview.com	3 Calls per Minute
Production/LIVE	To be provided upon onboarding	Based on contract

Create a new virtual account

Endpoint details

Endpoint URL	Method	Authentication requirements
`/api/v2/virtualaccount/create`	POST	`SVReferenceID` `CompanyId` `Device` `DateTimeStamp` `Authorization: Bearer`

Sample request

Create a New Virtual Account Request

curl --location 'https://sandboxapi.onesingleview.com/api/v2/virtualaccount/create' \
--header 'SVReferenceID:  SV123456' \
--header 'CompanyId: SINGLEVIEW1234' \
--header 'Device: web' \
--header 'DateTimeStamp: 2025-01-07T10:20:39' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJkYXRhIjoiTDNyMmpxV29JS2I4MTNodDBNeVN4WFRCZjlqUlNWQzFad3B5QnlkOVpHelZXR2ZwUmFQNUUrY3d6cVQ5bi9OV0lwR2V5STNNMkdPL1pqakd4ZG0yclJkVEZxY3lhWGNpWnZFejl0V1EySjQxK2VvSlk2ZjdJZkFsV3BKRi9VL1YydDEzMUtnRnVhcnd6MzVQY1UzbnFEV0p0UWlzIiwiaWF0IjoxNzY3NzYxODc3LCJleHAiOjE3Njc3NjU0Nzd9.lWDSB3Rk_TtdUbKyFcCdaE5XGo7UDiTu2kDcqEyU7vg' \
--header 'Content-Type: application/json' \
--data '{
  "Message": {
    "SVCreateVAReq": {
        "BankCode": "ALRAJHI",
        "ReferenceNumber": "43444125016234",
        "VirtualAccountInfo": {
          "PrimaryAccountNumber": "68200059703000",
          "SchemeId": "SVCOL123",
          "VAClientId": "SV123456789"
          "RemitterName": "singleview",
          "RemitterId": "4560345222",
          "CapAmount": "20",
          "Notification": "B",
          "EmailId": "user@test.com",
          "Phone": "5589655664"
        }
		}
		},
"Signature": "rZZ9alg/2k9B5uWSdnW3AfYswAMqA4HXyNX3jIzckWb4o37uS4eKFEQ3xRn/dBarN6EGjfaXiMSOPdKyyjjrgT80K5ReXzQ7cC1INuU79ozlLgK8yTFz+nq785geQ+He4PR+hD35DkF9qnela9qmcr3GhAXpTjZG12hmaJEyzeofh6q3p+jqLFd208eAImubnL6SbSBDEAi5SLRH1K2I1U77OmFNirrfGV8qd+gsi+lqgyF9mpNj6lzy/fJNNe0qEr2WHvG1R7E2g3EhqovDNanQt6RFgkWegtlE37Eyi5qO3xlTqu76317ZWfMI7jHxs48fOLTNtBCOwUboVze5Tw=="
}'

Request parameters

JSON Tag	Requirement	Description	Data type
Message	Mandatory	Header information (client credentials)	Object
SVCreateVARequest	Mandatory	Root node containing all the info to create a virtual account	Object
BankCode	Mandatory	Unique bank identification code `ALRAJHI` - Al Rajhi Bank	String
ReferenceNumber	Mandatory	Unique reference number for the request generated by the client Maximum length : 16 numeric characters	String
VirtualAccountInfo	Mandatory	Tag carrying information on virtual account specifications to be created	Object
PrimaryAccountNumber	Mandatory	Primary account number to which the virtual account is linked	String
SchemeId	Mandatory	Identifier of the virtual account scheme provided by the partner bank to the client	String
VAClientId	Mandatory	Unique client identifier for the virtual account provided by the partner bank to the client	String
RemitterName	Mandatory	Name of the remitter associated with the virtual account	String
RemitterId	Mandatory	Unique alphanumeric identifier generated by the client for the remitter	String
CapAmount	Mandatory	Maximum amount allowed for the virtual account	String
Notification	Mandatory	Notification preference to be specified as: `E` for email `S` for SMS `B` for both `N` for none	String
EmailId	Conditional Optional if Notification = `N`	Email address to receive notifications for the concerned virtual account Mandatory if Notification = `E` or `B`	String
Phone	Conditional Optional if Notification = `N`	Phone number to receive notifications for the concerned virtual account Mandatory if Notification = `S` or `B`	String
Signature	Mandatory	Encrypted string generated using a Private Key/CA-Signed Certificate with SHA-256 and RSA (JCE Signature)	String

Sample response

Create Virtual Account Response

{
  "SVCreateVAResp": {
    "BankCode": "ALRAJHI",
    "ReferenceNumber": "43444125016234",
    "StatusCode": "Completed",
    "StatusDetail": "Virtual account created successfully",
    "VirtualAccountInfo": {
      "VirtualAccountNumber": "000000990007351239014",
      "VirtualIBAN": "SA5680900000735991239014",
      "RemitterId": "4560345222",
      "RemitterName": "singleview",
      "CapAmount": "20"
    }
  }
}

Response parameters

JSON Tag	Description	Data type
SVCreateVAResp	Root node	Object
BankCode	Unique bank identification code `ALRAJHI` - Al Rajhi Bank	Object/Array
ReferenceNumber	Unique reference number for the request generated and passed by the client in the request	String
StatusCode	Code representing status of the transaction processing	String
StatusDetail	Details of the status code represented for the transaction processing	String
VirtualAccountInfo	Tag carrying information on the created virtual account	Object
VirtualAccountNumber	Unique account number of the created virtual account Al Rajhi bank provided BBAN in this field	String
VirtualIBAN	IBAN assigned to the new created virtual account	String
RemitterId	Client-generated identifier of the remitter	String
RemitterName	Name of the remitter associated with the virtual account	String
CapAmount	Maximum amount configured for the virtual account	String

Status Codes & Information

StatusCode	StatusDetail
Completed	Virtual account created successfully.
Failed	Bank response description
Response_Timeout	Timeout! Unable to get response from the bank. Please contact SingleView support.

Categories

GENERAL INFORMATION

GETTING STARTED

AUTHENTICATION

Data APIs

Payment APIs

SADAD

Virtual Accounts

SME Onboarding (Draft)

RESOURCES

API Archives

Domain details

Create a new virtual account

Endpoint details

Sample request

Sample response

Status Codes & Information