SADAD bill enquiry

SADAD Bill Enquiry API enables businesses to retrieve bill information and outstanding payment details for bills registered within the SADAD ecosystem.

This service allows organizations to validate bill information before initiating payment, helping reduce payment failures and improve reconciliation accuracy.

Typical use cases include bill presentment, customer payment journeys, automated bill processing, and financial reconciliation workflows.

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
Ensure that the SequenceNumber is unique for each transaction. Payments with same sequence number appear as duplicate transactions and affects their processing and enquiry operations.

🌐
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

Make SADAD bill enquiry

Endpoint details

Endpoint URL	Method	Authentication requirements
`/api/v2/sadad/bill/enquiry`	POST	`CompanyId` `SVReferenceID` `DateTimeStamp` `Device` `Authorization: Bearer`

Sample request

SADAD Bill Enquiry Request

curl --location 'https://sandboxapi.onesingleview.com/api/v2/sadad/bill/enquiry'
--header 'CompanyId: MYCOMPANY'
--header 'SVReferenceID: SV150619940615'
--header 'DateTimeStamp	:2025-01-02T10:20:39'
--header 'Device: Web'
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJkYXRhIjoiTDNyMmpxV29JS2I4MTNodDBNMlZ4WGpFZmR6WFNWaTFad3B5QnlkOVpHelZXR2ZwUmFQNUV1TXl6S1Aybi94Y0lwR2V5STNNMkdPL1pqakd4ZG0yclJKUkdhRXlaWGNpWnZnOHArMWIyOGtOQTVkZ0VKajVVSEdiTmtNPSIsImlhdCI6MTczNTgwMTQ3NywiZXhwIjoxNzM1ODA1MDc3fQ.Bh7LFkvxNFrLe9dmH5rURWjGpES-u4z2EGeyrNM7z6E'
--header 'Content-Type: application/json'
--data '{
"Message": {
  "OSVSadadBillEnquiryRequest": {
    "TransactionType": "SBE",
    "CompanyCode": "OSV0001",
    "MessageDescription": "Electricity Bill Office",
    "BankCode": "ALRAJHI",
    "AccountNumber": "SA6181234204608017172770",
    "TransactionData": {
      "SequenceNumber": "12345678912",
      "BillCategory": "50",
      "BillerId": "002",
      "SubscriberNumber": "123456781"
    }
  }
},
"Signature": "nqusYO9e8l+WzuOSvKysOPaN5mQaH6EujqvhTqyTHApGh+zEZUjQG7jQP1cEC5opOqU1QZj4m1d0bHwTYGXYmHLypQb+d1IncMvKA+sLFVgu5wMi6PqnDg5+e6hktgwYRJAGdQs9Om8B8LUnCKYKgghKR2roFU0yhu0Qs4y8+NZPx1a1L7tzs01ZyxnNxPe5lCSgtJHsQX5Cqb/gEDb64uYpN/=="
}'

Request parameters

JSON Tag	Requirement	Description	Data type
Message	Mandatory	Tag carrying the request information	Object
OSVSadadBillEnquiryRequest	Mandatory	Root node containing all the SADAD bill enquiry information	Object
TransactionType	Mandatory	Type of transaction to be mentioned as `SBE`	String
CompanyCode	Mandatory	Unique company identification code provided by bank	String
MessageDescription	Mandatory	Details of the transaction	String
BankCode	Mandatory	Unique bank identification code `ALRAJHI` - Al Rajhi Bank `SABB` - Saudi Awaal Bank `BSF` - Banque Saudi Fransi `ANB` - Arab National Bank `NCB` - Saudi National Bank `RIYADH` - Riyadh Bank	String
AccountNumber	Mandatory	Valid SAR account number associated with the respective SADAD bill	String
TransactionData	Mandatory	Tag carrying information on the requested SADAD bill	Object
SequenceNumber	Mandatory	Unique number generated by the client representing the transaction Length of input: 16 numeric characters	String
BillCategory	Conditional Mandatory for Al Rajhi Bank & SAB	Unique bill category of the SADAD bill to be mentioned as `50` for postpaid and `06` for prepaid bill services	String
BillerId	Mandatory	Unique and valid biller identification details	String
SubscriberNumber	Mandatory	Unique subscriber identification details	String

Sample response

SADAD Bill Enquiry Response

{
  "OSVSadadBillEnquiryResponse": {
    "TransactionType": "SBE",
    "CompanyCode": "OSV0001",
    "BankCode": "ALRAJHI",
    "StatusCode": "Completed",
    "StatusDetail": "Bill enquiry successful.",
    "TransactionData": {
      "SequenceNumber": "12345678912",
      "BillerID": "002",
      "SubscriberNumber": "123456781",
      "AmountDue": "168.25",
      "DueDate": "20260515",
      "ServiceType": "ELCT"
    }
  }
}

Response parameters

JSON Tag	Description	Data type
OSVSadadBillEnquiryResponse	Tag carrying information on bill enquiry response	Object
TransactionType	Details on type of message to be displayed as `SBE`	String
CompanyCode	Unique company identification code provided by bank	String
BankCode	Unique bank identification code `ALRAJHI` - Al Rajhi Bank `SABB` - Saudi Awaal Bank `BSF` - Banque Saudi Fransi `ANB` - Arab National Bank `NCB` - Saudi National Bank `RIYADH` - Riyadh Bank	String
StatusCode	Status code of the bill enquiry response as `Completed`, `Failed` or `Response_Timeout`	String
StatusDetail	Details on the status code displayed	String
TransactionData	Tag carrying information on the SADAD bill enquiry	Object
SequenceNumber	Unique sequence identification of the bill generated by the client	String
AmountDue	Details of amount due for the bill. This tag becomes conditional when amount is negative or zero.	String
DueDate	Due date for the payment of bill amount (in `YYYYMMDD` format). This tag becomes conditional when amount is negative or zero.	String
ServiceType	Details on type of the bill service	String

Status codes & information

StatusCode	StatusDetail
Completed	Bill enquiry successful.
Failed	Response as provided by the bank
Response_Timeout	Timeout! Unable to get response from the bank. Please try again in few minutes or contact SingleView support.

Categories

GENERAL INFORMATION

GETTING STARTED

AUTHENTICATION

Data APIs

Payment APIs

SADAD

RESOURCES

API Archives

Domain details

Make SADAD bill enquiry

Endpoint details

Sample request

Sample response

Status codes & information