Overview

Our API allows you to use some of the most important functionalities of ANB platform to perform jobs in your app using ANB services & customers' data.

 

Prerequisites

To use the SADAD service, you need to do the following:

  • Register/Login to the anb Developer Portal.
  • Create an app.
  • You should now have a client id and secret associated with your app.
  • Get an access token from our auth service using your client id and secret.

 

To create a new application:

  • Log in to your account. Then navigate to Apps > Add App.
  • In the App name field, enter a name for your application.
  • In the APIs field, select B2B Payment Sandbox, and click ADD APP.
  • Get an access token from our auth service using your client id and secret.
Sandbox access details
Attribute Value
client_id The client_id for your application on the Developer Portal
client_secret The client_secret for your application on the Developer Portal

 

How to integrate with ANB?

  1. Make sure to read and to understand API documentation.

  2. Send an email to API@anb.com.sa with the following details

  3. You will get an email from API@anb.com.sa with client id and secret

 

Error codes

HTTP Status code
Status Code Message Description
200 OK Transaction is successful
500 Internal Server Error Something went wrong internally
400 Bad Request Request is not valid

 

Error Codes
Status Code Description
I000000 Successful Operation
E020051 Language code should be ENGLISH or ARABIC
E020358 Associate ID is mandatory for the service 058
E620001 The signon information provided in the query in invalid
E620002 The date range supplied in invalid
E620003 The specified Biller does not exist in system
E620004 Bank is not active
E620005 Neither Biller ID nor customer ID specified in query
E620006 Customer?s logon ID not active :
E620007 Customer ID is not specified in query
E620008 Customer does not exist in system
E620009 The following property is null or undefined
E620010 Access channel is mandatory
E620011 Biller ID is mandatory if billing account / bill number is provided
E620012 Display label not found for statement
E620013 Invalid customer, like ?invalid customer?, or ?could not obtain customer information'
E620014 Error while fetching Service Account Presentment Agreement for the entities provided'
E620015 System specified message for error while fetching Statement(s)
E620016 Error populating bill record aggregate in the response
E620017 Error while fetching global (SADAD) message for the response
E620018 Error while applying one of the rules
E620019 Error while fetching fake Statement(s)
E620020 Specified entity does not exist in the system
E620021 Merchant key for Service Account Presentment Agreement not found in the system
E620022 The query passed in null
E620023 Null / invalid date format :
E620024 Audit failure! The process could not be audited
E620025 Customer ID is mandatory for customer
E620026 Proxy customer ID is mandatory for proxy customer
E620027 Biller is not active :
E620028 Account is not active :
E620029 Query successful, but fetch limit reached. Some records may not have been fetched
E620030 No bills found matching the search criteria
E620031 Query response failed schema validation
E620032 Internal error
E620033 Invalid XML. Schema validation failed
E620034 Failed to get Sender ID, Receiver ID or Message Code from XML message
E620035 Failed to get message parameters from config file
E620036 Failed to read MessageDetails.cnf file
E620037 Failed to validate the message
E620038 Failed to query bill
E620039 Failed to sign or persist response message
E620040 Utility Bill host Server is not running
E620041 Communication problem with utility Bill host server
E620042 Overpayment or underpayments is not allowed
E620043 Cannot make overpayment
E620044 Cannot make underpayment
E620045 Bill Not Found
E620046 Bill has expired. Payments cannot be made on expired bills
E620047 Payable amount should be greater than zero
E620048 Your account has been disabled. Please contact the Administrator
E620049 Account not found
E620050 Biller is not active
E620051 The specified Biller does not exist in the system
E620052 Internal Error!
E620053 Failure (see embedded error code(s))
E620054 Issuer Bank not found
E620055 Acquirer Bank not found
E620056 There is no enough data provided to complete the transaction
E620057 Issuer Bank Not Active
E620058 Acquirer Bank Not Active
E620059 Cannot make multiple payments on the same Account/Bill in a single request
E620060 Access Channel not found
E620061 Payment validation request limit exceeded
E620062 Access Channel not Active
E620063 Branch Code is missing
E620064 District Code is missing
E620065 Payment method is missing
E620066 Access Channel is missing
E620067 You have been disabled. Please contact the Administrator
E620068 Verification failed for the certificate used for signing the data
E620069 Signature verification failed
E620070 Payment Confirmation failed
E620071 Customer not found
E620072 One or more accounts not found
E620073 One or more associations between the customer and its accounts not found
E620074 Failed to inquire Customer Profile
E620075 Failed to add Customer Profile
E620076 Failed to delete Customer Profile
E620077 Amount does not match
E620078 Sadad PmtId missing
E620079 Payment is a part of the group
E620080 Payment has been advanced to a state wherein advice cannot be performed
E620081 Bank PmtId missing
E620082 Value date is missing
E620083 Sadad Timeout
E620084 SADA General Failure
E620085 TimeOut
E620086 Channel Is Not Enabled
E620087 Fund Transfer Error
E620088 Fund Transfer Timeout
E620089 Message Response Error(As an Inner Error Only)
E620090 ChannelTimeOut
E620091 ATM Has Terminated The Payment
E620092 Account has Insufficent Funds
E620093 Account is Not Valid
E620094 Communication Error With SADAD
E620095 Payment Already Advised Error
E620096 Payment Already Terminated Error
E620097 Invalid Message Type Coming From The Channel
E620098 Tuxedo Unable To Connect To Host
E620099 Tuxedo Connected To Host But No Response
E620100 Your request has failed. Please try again later
E620101 The requested biller is not subscribed for Fee Query service
E620102 The supplied RQUID has already been used
E620103 Bank is not authorized to access this service
E620104 The selected access channel is not permitted to perform MOI payments
E620105 Fee amount is less than or equal to zero
E620106 The supplied service ID is not of a service provided by the biller
E620107 Branch code does not exist:
E620108 District code does not exist :
E620109 Branch code is missing
E620110 District code is missing
E620111 Payment already exists in the system for request (RQUID)
E620112 Payment Amount Validation failed for CIP
E620113 CIP Validation failed for payment type :
E620114 CIP validation failed for account :
E620115 Account does not exist in the system :
E620116 Payment Amount is not in range
E620117 The payment type does not exist
E620118 Payment Check digit is missing
E620119 Exact payment is required
E620120 Payment is less than the minimum allowed amount
E620121 Payment is greater than the maximum allowed amount
E620122 Invalid or missing payment method
E620123 Billing account must not be supplied for voucher payment type :
E620124 Bill number must not be supplied for voucher payment type :
E620125 No vouchers available for the requested amount
E620126 Billing account is not supplied
E620127 Acquirer BankId is missing
E620128 The count of payments validated and the payments count in Advice request dont match
E620129 No Payments found for the groupPmtId provided
E620130 Status aggregate defining advice code is missing
E620131 Payment already exists in the system with Bank PmtId:
E620132 Duplicate Bank PmtId found in the request
E620133 Advice can only be performed by the Bank that requested payment validation
E620134 Bank Id in the request does not match the Bank Id in the system
E620135 The Customer Id in the request does not match the Customer Id in the system
E620136 The Service Id in the request does not match the Service Id in the system
E620137 The Beneficiary Id in the request does not match the Beneficiary Id in the system
E620138 The Partner service aggregate is missing
E620139 Customer-Account association not found
E620140 Biller assigned customer association cannot be deleted
E620141 One or more associations between the customer and its accounts are biller assigned
E620142 Failed to get Signature value
E620143 Failed to get Certificate details from partner profile
E620144 Failed to get partner profile from config file
E620145 Failed to read PartnerDetails.cnf
E620146 Failed to read SADADProfile.cnf file
E620147 Failed to retrieve Biller Info
E620148 Failed to attach signature to the message
E620149 Failed to sign the data
E620151 Incorrect Beneficiary Id
E620152 Incorrect amount entry
E620153 Wrong amount
E620154 Citizen record not found
E620155 Incorrect sponsor Id entry
E620156 Refund Amount is Exceeding the available Amount
E620157 Not Enough Balance
E620158 Incorrect key field entry
E620159 Occupation not found
E620160 Beneficiary ID is not Supplied in the Request
E620163 Invalid customer Id
E620164 Citizen not found
E620165 Alien not found
E620166 Visitor not found
E620167 Invalid customer Id
E620168 Customer cannot perform the required service
E620170 Operation cannot be completed, try again later
E620171 Operation cannot be completed, check with bank
E620172 Operation cannot be completed, check with NIC
E620173 Duplicate Refund Id
E620174 No Payment Found
E620175 Unable To Get Customers Account
E620176 Unable to Get the Payment
E620177 Unable to Log Refund Query Request
E620178 Duplicate Incomplete Refund
E620179 Unable to Log Refund Query Response
E620180 Internal Error
E620181 Unknown Error, check with NIC
E620182 Invalid or missing HTTP Header sender-id or rquid or destination-id
E620183 Missing data stream or valid content-type application/octet-stream
E620184 Invalid message code. Expected RINQRQ
E620185 Invalid message type. Expected RefundInqRq
E620186 Failed to deliver refund query request to biller
E620187 Invalid Duration / Period
E620188 Fee does not exist for given duration
E620189 No Fee Required
E620190 Fee Amount is Zero
E620191 Invaild job category
E620192 Incorrect number of dependents
E620193 Invalid Visa number
E620194 Invalid passport type
E620195 Citizen is suspended
E620196 Citizen is either dead or nationality withdrawn
E620197 Incorrect citizen Id
E620198 Beneficiary ID Is not found
E620199 Citizen ID is Not Found
E620200 Invalid alien Id
E620201 Alien ID is Not Found
E620202 Alien has died
E620203 Alien is naturalized
E620204 Alien has exited and not returned
E620205 Alien is outside the kingdom
E620206 Visitor ID is Not Found
E620207 Travel record (border crossing) not found
E620208 Visitor has exited the kingdom
E620209 Visitor Visa not found
E620210 Alien Sponsor record not found
E620211 Extension can only be granted to an Alien head of household
E620212 The Id entered in not for a dependant alien
E620213 Alien Visa not found
E620214 Alien Passport Not Found
E620215 Pilgrim is not found
E620216 The HOH Of The Current Dependent Is Not Found
E620217 Dependant has a separate Iqama
E620218 Separation Is Not Allowed For The Current Dependent
E620219 Exceeding maximum number of years for Iqama
E620220 The citizen wife Id should be for a female
E620221 Sponsor name not found
E620222 Alien is suspended
E620223 No Visa requested
E620224 Incorrect number of Visass entry
E620225 Invalid Visa Type
E620226 Invalid vehicle sequence number
E620227 Vehicle Sequence Number is not Supplied in the Request
E620228 Incorrect current owner Id entry
E620229 Vehicle current registration type is not found
E620230 Vehicle record not found
E620231 new license plate record not found
E620232 The service is only valid for old vehicle registration type
E620233 Vehicle new owner can not be same as the current owner
E620234 Vehicle owner record not found
E620235 Vehicle Current Owner ID is not Supplied in the Request
E620236 Invalid vehicle new owner Id
E620237 Vehicle New Owner ID is not Supplied in the Request
E620238 Invalid numeric part of the new license plate
E620239 The Numeric Part of the New License Plate is not Supplied in the Request
E620240 Vehicle registration type is invalid
E620241 Vehicle Registration Type is not Supplied in the Request
E620242 The supplied license plate number can not be found
E620243 Vechicle body type is invalid
E620244 Vehicle Body Type is not Supplied in the Request
E620245 Vehicle custom card number is invalid
E620246 Vehicle Custom Card Number is not Supplied in the Request
E620247 This service is only validfor new vehicle registration type
E620248 The vehicle status is not valid for the requested service
E620249 Vehicle custom card number is not found
E620250 The vehicle custom card number is already in use with another vehicle
E620251 The Request Type is Invalid
E620252 Invalid license type
E620253 The Request Type is not Supplied in the Request
E620254 The License Type is not Supplied in the Request
E620255 The Beneficiary ID is not Supplied in the Request
E620256 The Request Type is Invalid
E620257 Driving license status not found
E620258 Driving license not found
E620259 Unpaid Traffic Violation(s) Found For The Beneficiary
E620260 Invalid event actual date
E620261 Citizen has a nationality withdrawn status
E620262 Death registration requested for a dead person
E620263 Can not issue a replacement ID Card for a dead citizen
E620264 Only male citizens can perform the birth registration service
E620265 Event actual date is greayer than current da
E620266 Unable to Log FeeInquiry Request Caused by Error in SQL Execution
E620267 Unable to Log FeeInquiry Response Caused by Error in SQL Execution
E620268 This Operation is Blocked from 11:30PM to 12:30PM oclock
E620269 Unknow Error, check with NIC
E620270 Unsuccessful
E620271 Violation Already Paid
E620272 Violation Cancelled
E620273 Violation Not Payable Online
E620274 Violation does not belong to Customer
E620275 No Violations found for Customer
E620276 Refund message is from a bank that is not subscribed to the refund process
E620277 The Refund ID provided does not match an existing Refund record in SADAD
E620278 Refund is not a Cash Refund
E620279 Refund record has an invalid status of Refund Status
E620280 Customer ID does not match the refund record
E620281 Customer ID Type does not match the refund record
E620282 Incorrect PIN number
E620283 Biller ID does not match the refund record
E620284 Bank ID does not match the refund record
E620285 Refund record is expired
E620286 Refund ID must start either with the biller?s ID or the Bank?s ID
E620287 Bank not found in Sadad
E620288 The bank is not activated
E620291 Cannot process Refund request now, please try later
E620292 Data did not receive from Host System.
E620293 Socket Timeout Exception Please Check with MB Supprot Team.
E620294 SocketException Please Check with MB Supprot Team.
E620295 IOException Please Check with MB Supprot Team.
E620296 UnknownError Please Check with MB Supprot Team.
E620297 NullPointerException Please Check with MB Supprot Team.
E620298 Exception has been occured during the process.
E620299 Unhandled Java: Exception thrown by MB
E620300 The Required Driving License validity Duration is Invalid
E620301 Invalid message code. Expected FINQRQ
E620302 Invalid message type. Expected FeeInqRq
E620303 Date must be Gregorian
E620304 Fee Duration Date value cannot be less than todays date
E620305 The Associate ID is Invalid
E620306 The maximum allowed period to inquiry associates fees is 10 years
E620307 Dependent Birth Date cant be a future value
E620308 The Dependent Birth Date is Invalid
E620309 Payment Validation failed
E620310 Advice Status Code is not valid
E620311 Partner is not subscribed to use the requested service.
E620312 Bank is not registered with SADAD
E620313 Bank is deactivated in SADAD
E620314 The SADAD Bills ID provided does not exist
E620315 The SADAD Bills ID is no longer available to pay
E620316 Invoice details could not be retrieved, please try again
E620317 The Payer ID provided does not exist
E620318 There are no available invoices for the Payer ID provided
E620319 The supplier does not exist or cannot be found based on the search you have entered
E620320 Invalid bill query request.
E620321 MOIFeeAdvice MissMatch
E620322 Inactive Biller
E620323 Invalid Amount
E620324 Missing SPTN
E620325 Beneficiary id needed for prepaid accounts
E620326 Beneficiary OfficialIdType is required
E620327 The Beneficiary OfficialIdType is not valid
E620328 The allowed amount to be paid as a partial payment against this bill
E620329 Beneficiary id does not match with account owner id
E620330 Postpaid payment type not allowed for prepaid account
E620331 Customer Id is required
E620332 Beneficiary phone number is needed for prepaid service
E620333 Partial payments are not permitted
E620334 Amount entered is less than the minimum (partial payment) payable
E620335 Amount entered is greater than the invoice outstanding amount
E620336 Payment failure, please try again (catch all)
E620337 Invalid payment validation request provided.
E620338 More unpaid violation(s) exists
E620339 The Violator Id is Invalid
E620340 The Violator Id has an Invalid Check Digit
E620341 No Fines available for payment
E620342 The Visa cannot extended the Iqama Validity
   
E620338 More unpaid violation(s) exists
E620339 The Violator Id is Invalid
E620340 The Violator Id has an Invalid Check Digit
E620341 No Fines available for payment
E999970 Cast Exception
E999971 Conversation Exception
E999972 Sql Exception
E999973 User Exception
E999974 Receoverable Exception
E999975 Database Connection Issue
E999976 DataBase Timeout
E999977 MQ communication error
E999985 TCPIP Communication Error With the Host Systems(Connection Refused)
E999998 Unrecoverable database error
E999999 Unrecoverable integration error

 

Authentication

Authentication API is your way in to use the rest of services. All services require a Bearer token that you can get through below services.

 

Access Token

This is your starting point to use below APIs. You request a new token by supplying your client id and secret from the Developer Portal.

 

Customer Profile Management

These services will be used to Add, Delete and Inquire the customer profile from A4SADAD system.

 

Flow:

 

Profile

Customer profile Inquiry endpoint used to get the customer profiles details from SADAD.

 

Query Params
Fields Description R: Required
O:Optional
C:Conditional		 Length
LangPref Preferred Language R 10
POINum Customer Id R 50
POIType Customer Id Type R 50
NumOfRecs Number Of Records in the request R 1
BillingAcct Billing Account O 19
BillerId Biller Id O 3

 

Response
Field Description Always
StatusCode Request status code Yes
StatusDesc Request status Yes
HostName Host name No
HostStatusCode Host request status code Yes
HostStatusDesc Host request status description Yes
RqUID Unique Request ID No
ClientDt Request time stamp No
LangPref Echo From Request Yes
POINum Customer Id Yes
POIType Customer type Yes
NumOfRecs Record count Yes
IsInProf Is in profile boolean Yes
BillingAcct Billing account Yes
BillerId Biller id Yes

 

Create/Add Profile

Customer Profile Add endpoint used to add a new customer profile in SADAD system.

 

Request
Fields Description R: Required
O:Optional
C:Conditional		 Length
Sequence Number Sequence Number R 50
LangPref Preferred Language R 10
POI/POINum Customer Id R 50
POI/POIType Customer Id Type R 50
NumOfRecs Number Of Records in the request R 1
CustProfInfo/BillingAcct Billing Account O 19
CustProfInfo/BillerId Biller Id O 3

 

Response
Field Description Always
StatusCode Request status code Yes
StatusDesc Request status Yes
HostName Host name No
HostStatusCode Host request status code Yes
HostStatusDesc Host request status description Yes
RqUID Unique Request ID No
ClientDt Request time stamp No
LangPref Echo From Request Yes
POINum Customer Id Yes
POIType Customer type Yes
NumOfRecs Record count Yes
ProfStatus Profile status Yes
BillingAcct Billing account Yes
BillerId Biller id Yes
ProfUpdStatusCode Profile update status code Yes

 

Govt/MOI Fee Inquiry

This service will be used to inquire about MOI services. Once you received the response, then you will call the bill pay advice service to actually pay the fee.

 

Flow:

 

Fee Inq

This service brings the MOI fee details for a given POI and biller ID from SADAD system. This will be used to inquiry fee for Government services always.

 

Request
Fields Description R: Required
O:Optional
C:Conditional		 Length
Sequence Number Sequence Number R 50
LangPref Preferred Language R 10
POI/POINum Customer Id R 50
POI/POIType Customer Id Type R 50
ProxyPOI/POINum Customer ID number
This is mandatory only for branch channel, other than branch it is space.		 R/O 50
ProxyPOI/POIType Proof of identity type BTELLER-BTL R/O 50
ANBAcctNum Debit Account Number or Credit Card Number R 20
ANBAcctType 1- Normal Account.
2- Credit Card Account.		 R 1
CardExpDt Credit card expiration date:
YYYY-MM-DD		 R/O 10
BillerId MOI Biller Codes:
090- Residents Services
091- Driving License
092- Saudi Passports
093- Traffic Violation
094- Motor Vehicle
095- Labor Importation
096- Civil Registration
126- National Platform of Violation
127- Entry Ports Payments		 R 1
ServiceCode MOI Service Codes:
001- Extend Visitor Visa
002- Issue New Iqama
003- Renew Iqama
004- Exit Re-entry Visa ( Single)
005- Exit Re-entry Visa (Multiple)
006- Visa Cancellation
007- Transfer of Sponsorship
008- Replace Iqama
009- Transfer Dependant to be Head of Household
010- Transfer Head of Household to be Dependant
011- Transfer Dependant to a New Head of Household
012- Change of Occupation ,
013- Dependants Entry visa Fee Collection
014- Adding Dependent born inside Saudi Arabia after one Year from his Date Of Birth
015- Dependent Separation
016- Issue New Iqama for a Citizen’s wife
017- Birth Registration
018- Death Registration
019- Marriage Registration
020- Divorce Registration
021- Issue ID Card
022- Issue License
023- Issue License from Old License
025- Renew License
026- Renew Vehicle Registration
027- Transfer Owner
028- Re-issue Registration Card
029- Re-issue License Plate ( 1 plate only)
030- Export Vehicle
031- Exchange Plates by Owner
032- Exchange Plates Not by Owner
034- Sequence Number Inquiry 2 (New License Plates Only)
035- Issue New Passport
037- Renew Passport
038- Family Visa
039- Issue Visa
040- Traffic Violations by Violator ID
041- Query traffic violations by violation ID
042- Register Vehicle
043- Re-import vehicle
044- Transfer Plates (Give plates to registered vehicle without plates)
045- Changing Current Vehicle plate
046- Pay All Deportation Sentences Installments
047- Pay One Deportation Sentence Installment
049- Transform Vehicle Into Junk
050- Pay a Deportation Travel Ticket
052- Lost passport Fine
053- Issue Family Card
054- Other Fees and Fines
057- Extend Exit Reentry Visa Duration
058- Associate Fees for a Specific Associate Service ID
059- Associates Fees for All Registered Associates on the Head of Household Iqamah
060- List Violations by providing the Issuing entity and category ID
061- Replace Damaged License
063- Print Citizen Information
064- Replace Lost License
065- Entry Visa Fees
066- Exceeding The Visa Residency Duration
067- Retrieve The Beneficiary ID		 R 3
BranchCode BranchCode R 10
PaymentMethod CASH CCARD = Credit Card
EFT = Funds Transfer
ACTDEB = Debit to account		 O 32
BenId the beneficiary is the actual customer for the biller
049- Transform Vehicle Into Junk		 R 32
BenfIdtype the beneficiary Type is the actual customer for the biller, If the Beneficiary Id is not National ID, Iqama ID, Business ID, or Passport Id, then this O 3
BenName BeneficaryName O 128
SponsorId The Id of the Sponsor of Visa to the customer
Mandatory for the following services:
002- Issue New Iqama
009- Transfer Dependant to be Head of Household		 R/O 10
JobCategory 06- Farming Labor
20- Relatives (Family Visa)
21- Housing Labor
22- Shepherd Labor
23- Other
Mandatory for the following services:
002- Issue New Iqama
009- Transfer Dependant to be Head of Household		 R/O 2
IqamaDuration This value contains the duration of Iqama (In months 3,6,9,12,……. In multiples of 3 till max 300)
Mandatory for the following services:
002- Issue New Iqama
003- Renew Iqama
016- Issue New Iqama for a Citizen‟s wife
This value contains the duration of Iqama (In years 1,2,3).Mandatory and Applicable for only
009- Transfer Dependant to be Head of Household		 R/O 3
style="white-space: nowrap">DependentCount The Value of Number of Dependents of the customer,
Mandatory for the following services:
013- Dependents Entry Visa Fee Collection.
014- Adding Dependent born inside Saudi Arabia after one year from his date of birth		 R/O 6
VisaCount This is the Value of Number of visas based on the number of dependents or employees,
Mandatory for the following services:
038- FamilyVisa
039- Labor Visa		 R/O 6
VisaType 01- Work Visa
02- Seasonal Work Visa
03- Temporary Work Visa Single Travel
04- Temporary Work Visa Multiple Travels
Mandatory for the following service:
039- Labor Visa		 R/O 2
VisaNum The Saudi Visa Number
Mandatory for the following services:
006- Visa Cancellation		 R/O 36
CitizenId This is the Id value of the Saudi citizens
Mandatory for the following service:
016- Issue New Iqama for a Citizen‟s Wife		 R/O 10
EventDt Mandatory for the following services:
017- Birth Registration
018- Death Registration
019- Marriage Registration
020- Divorce Registration
021- Lost ID Cards Registration		 R/O 19
LicenseType 01 -Temporary private license
02 -Motorcycle
03 -Private
04 -Public Taxi
05 -Small Carriage Vehicle
06 -Medium Truck
07 -Heavy Truck
08 -Heavy Equipment Vehicle
Mandatory for the following services:
022 -Issue License O
023 -Issue License from Old License
024-Replace license
025-Renew License		 R/O 2
VehicleSeqNum This is the unique number of the vehicle provided by the manufacturer
Mandatory for the following services:
026 -Renew Vehicle Registration
027 -Transfer Owner
028 -Re-issue Registration Card
029 -Re-issue License Plate ( 1 plate only)
030 -Export Vehicle
031 -Exchange Plates by Owner
032 -Exchange Plates Not by Owner 044 - Transfer Plates (Give plates to registered vehicle without plates)
045 - Transfer Plates (changing current vehicle plates)
049 - Transfer vehicle to junk		 R/O 36
NewOwnerId This is the Id of the person to whom the vehicle registration will be transferred
Mandatory for the following services:
027 -Transfer Owner
032 -Exchange Plates Not by Owner,
032-Exchange Plates Not by owner,
049 - Transform Vehicle Into Junk		 R/O 10
ViolationId This is the numeric value present in the violation ID
Mandatory for the following services:
041 - Query traffic violations by violation ID		 C 10
BodyType Motorcycle 2 tires
2 - Motorcycle 3 tires
3 - Motorcycle 4 tires
4 - Small car 2 doors
5 - Small car 4 doors
6 - Big car 4 doors
7 - 2 doors convertible car
8 - 4 doors convertible car
12 - Truck less than 3500 KG
13 - Truck
14 - Tank Wagon
15 - Dump truck
16 - 12 seats bus or less
17 - Bus with more than 12 seats
19 - Heavy utility car
20 - Utility car for public works
This represents the body type
Mandatory for the following service:
042 - Register Vehicle
043 - Re-import vehicle
044 - Transfer Plates (Give plates to registered vehicle without plates)
045 - Transfer Plates (changing current vehicle plates)		 R/O 3
NewRegType 01 - Private
02 - Public transportation
03 - Private transportation
08 - Exported
09 - Diplomatic
10 - Motorcycle
11 - Temporary
Mandatory for the following service:
042 - Register Vehicle
043 - Re-import vehicle
044 - Transfer Plates (Give plates to registered vehicle without plates)
045 - Transfer Plates		 R/O 2
PassportType 01 -Normal
02 -Diplomatic
03 -Private
04 -Travel Document
Mandatory for the following service:
035 -Issue New Passport
036 -Re-issue Passport
037 -Renew Passport		 R/O 2
VehCustCardNum For future use and currently will not be handled by A4SADAD
Mandatory for the following service for vehicle custom card number:
042 - Register Vehicle
043 - Re-import Vehicle		 R/O 10
LicenseDuration This value contains the duration of license in years
Mandatory for the following services:
022 -Issue License
023 -Issue License For Old
025 -Renew License
Possible Values:
01
02
05
10		 R/O  
MultiCurrency 0-the payment is not using multi-currency transaction
1-the payment is using multi-currency transaction		 O 1
Currency The currency used in the multi-currency payment O 3
ExRate Exchange rate value
(leading sign followed by zeros ) with decimal point		 R/O 19
ValidityDuration Validity Duration:-
01 - One Year
02 - Two Years
03 - Three Years
04 - Four Years
05 - Five Years
10 - Ten Years		 R/O 2
Visa Duration Visa Duration:-
30 - 30 days
60 - 60 days
90 - 90 days
120 - 120 days
150 - 150 days
180 - 180 days
210 - 210 days
240 - 240 days
270 - 270 days
300 - 300 days
330 - 330 days
360 - 360 days
390 - 390 days
420 - 420 days
450 - 450 days
480 - 480 days
510 - 510 days
540 - 540 days
570 - 570 days
600 - 600 days
630 - 630 days
660 - 660 days
690 - 690 days
720 - 720 days
750 - 750 days
780 - 780 days
810 - 810 days
840 - 840 days
870 - 870 days
900 - 900 days
930 - 930 days
960 - 960 days
990 - 990 days
1020 - 1020 days
1050 - 1050 days
1080 - 1080 days		 R/O 4
IssuanceReason Issuance Reason:-
01 - First Time Issuance
02 - Renewal
03 - Lost
04 - Stolen
05 - Damaged
06 - Information Update		 R/O 2
CardVerNum Two digits on the card.
Mandatory when IssuanceReason is:
03 - Lost
04 - Stolen
05 - Damaged
Optional for IssuranceReason is:
01 - First Time Issuance
02 - Renewal
06 - Information Update		 R/O 2
VerdictNum Verdict Number R/O 10
AssociateID Associate ID
• 10 digits for the associated alien Iqama Id related to the service 058
• This field is mandatory for service 058		 R/O 10
FeeDurationEndDt Fee Duration End Date (in HIJRI)
• This field to applicable for the services 058 and 059
YYYY-MM-DD		 C 10
DependentDOB Dependent Date of birth (in HIJRI)
• This field is applicable to service 014 YYYY-MM-DD		 C 10
IssuingEntityID Issuing Entity ID
• This field is applicable to service 060		 R/O 8
ViolationCategoryID Violation Category ID
• This field is applicable to service 060		 R/O 4

 

Response
Field Description Always
StatusCode Request status code Yes
StatusDesc Request status Yes
HostName Host name No
HostStatusCode Host request status code Yes
HostStatusDesc Host request status description Yes
RqUID Unique Request ID No
ClientDt Request time stamp No
LangPref Echo From Request Yes
BenName Beneficiary Name Yes
POINum Customer Id Yes
POIType Customer type Yes
GroupPayId Group payment ID Yes
SADADTrnNum For Branches only, this field will be used to return SPTN & BNKPTN. The first 16 digits for SPTN and the second 16 digits for BNKPTN. Yes
TotalFeeAmt This value indicates the amount of fees paid for the service which beneficiary had subscribed. Yes
RecordCount Number of times MOIFeeInqDtls repeats Yes
ProfUpdStatusCode Profile update status code Yes
FeeType Fee Type Yes
FeeDtlsAmt Fee details amount
Examples of valid values:		 Yes

 

Bill Inquiry (Pvt Billers)

Bill Inq

This service will be used to get the due amount that needs to be paid and the status of bill. Normally this service will be used for non-government entities like STC etc.
If we doing some recharge then we don't need to call this service.

 

Request
Fields Description R: Required
O:Optional
C:Conditional		 Length
Sequence Number Sequence Number R 50
LangPref Preferred Language R 10
POI/POINum Customer official Id is a unique identifier for a bill-paying entity, including people and companies. O 50
POI/POIType Proof of identity type. Customer ID Type Copy of Iqama National ID Passport Number O 50
BillingAcct Bill account number R 20
BillerId Partner need to maintain the list of SADAD billers.
001- STC
002– SCECO
003 - NCCI
004 – Marafiq
005 – Mobily, etc		 R 3
SubscriberNum Bill Subscriber Number R 19

 

Response
Field Description Always
StatusCode Request status code Yes
StatusDesc Request status Yes
HostName Host name No
HostStatusCode Host request status code Yes
HostStatusDesc Host request status description Yes
RqUID Unique Request ID No
ClientDt Request time stamp No
LangPref Echo From Request Yes
RecordCount No of times BillDtls repeats Yes
BillStatus BillPaid -The bill is fully paid and the net due amount is set to zero BIllPartialPd -One or more payments have been applied to the bill, but an outstanding balance remains BillOverPd -The bill has a net due amount less than zero BillUnpaid -No payments have been applied to the bill. BillDeactive -Bill is no longer payable Yes
CurrAmt Current bill Amount Yes
ExactPmtRqd Exact payment required flag Yes
FeeType Fee type Yes
BillCategory CIP' - Customer Initiated Payments 'HTOL' - High Toll Bills Yes
SvcType Service Type Yes
BillCycle Bill Cycle Yes
DisplayLabel Extra information for customer (e.g. customer name, contract number…) Yes
BillNum Bill number Yes
BillingAcct Billing account Yes
BillerID F001- STC
002 – SCECO
003 – NCCI		 Yes
AmtDue Bill amount to be paid Yes
BillDueDate Close Date of the Bill YYYY-MM-DDTHH:MM:SS Yes
NoOfPmtRangeInfo No of times payment range info repeats Yes

 

Bill Pay Validation (Pvt Bill Payment)

Normal Bill Payment

This service will be used to pay bill for normal biller or other then MOI biller. For example STC or telco bill etc..

 

Request
Fields Description R: Required
O:Optional
C:Conditional		 Length
Sequence Number Sequence Number R 50
LangPref Preferred Language R 10
POI/POINum Customer official Id is a unique identifier for a bill-paying entity, including people and companies. This field is mandatory for non-branch channel and optional for branch R/O 50
POI/POIType Customer ID Type is mandatory for non-branch channel and optional for branch. Mapping with A4SADAD.
Passport Number
BTELLER
Business ID
Copy of Iqama
National ID		 R/O 50
proxyPOI/POINum Customer ID number.This is mandatory only for branch channel, other than branch it is space R/O 50
ProxyPOI/POIType Proxy iCustomer ID Type This is mandatory only for branch channel, other than branch it is space Ex. BED = Bank Emp, BTL = Bank Teller *required if customer type is blank - used for customers paying cash R/O 50
BillPayValInfo/RecordCount Number of times BillDtls repeats R 3
BillPayValInfo/BillPayValDtls/CurrAmt Current Amount R 19
BillPayValInfo/BillPayValDtls/TrnDt Transaction Date R 19
BillPayValInfo/BillPayValDtls/ValDt Most of the time trnDt and ValDt will be same but if you make a transaction on non-business day then trnDt will be the same day but valDt will be the immediate next working day. R 19
BillPayValInfo/BillPayValDtls/BillCycle Bill Cycle Number R/O 16
BillPayValInfo/BillPayValDtls/BillNum Bill Number.This field is optional if billing account is provided R/O 19
BillPayValInfo/BillPayValDtls/BillingAcct Bill Subscriber Number. This field is optional if bill number is provided R/O 19
BillPayValInfo/BillPayValDtls/BillerID Biller ID R 3
BillPayValInfo/BillPayValDtls/BranchCode Default Branch number 0160 R 10
BillPayValInfo/BillPayValDtls/PaymentMethod CASH
CCARD = Credit Card
EFT = Funds Transfer
ACTDEB = Debit to account		 R 6
BillPayValInfo/BillPayValDtls/PaymentType POST = Post Paid(default)
RCHG = Recharge
RNEW = Renewal
RDEP = Roaming deposit
RADV = Advance payment for roaming		 R 4
BillPayValInfo/BillPayValDtls/ServiceType CIP -Customer Initiated Payment
ELCT -Electricity
PHON -Phone
GSM -Mobile phone service – a subtype of PHON
LLIN -Land Line
phone service – a subtype of PHON
INSR -Insurance
BKSV -Bank Service
GOVT -Government Service
MED -Medical
CCRD -Credit Card
UTIL -Utility
PCIN -Personal Computer Payment Installment
EXAM -University Exam Fees		 R 4
BillPayValInfo/BillPayValDtls/PaymentInfo Payment Reference Information” value must match the BillRefInfo value attached to the bill. However, this value should be returned if it was included in the bill inquiry response R/O 80
BillPayValInfo/BillPayValDtls/ANBAcctNum Debit Account Number or Credit Card Number R 20
BillPayValInfo/BillPayValDtls/ANBAcctType ANB Account Type
1-Normal Account
2-Credit Card Account		 R 1
BillPayValInfo/BillPayValDtls/CardExpDt Credit card expiration date, with format (yyyyMMdd). This field is mandatory for credit card account only C 10
BillPayValInfo/BillPayValDtls/MultiCurrency 0-the payment is not using multi currency transaction
1-the payment is using multi currency transaction		 R/O 1
BillPayValInfo/BillPayValDtls/Currency The currency used in the multi currency payment R/O 3
BillPayValInfo/BillPayValDtls/ExRate Exchange rate value R/O 18
BillPayValInfo/BillPayValDtls/BenfId For Mobile Prepaid Payments R/O 50
BillPayValInfo/BillPayValDtls/BenfIdType Debit Account Number or Credit Card Number R 20
BillPayValInfo/BillPayValDtls/ANBAcctType For Mobile Prepaid Payments:
Passport Number
BTELLER
National ID
Business ID
Copy of Iqama
Comm. Reg.		 R/O 50
SMSInfo/MobileNum Customer mobile number R/O 20
MSInfo/SMSPreferLang Customer SMS preferred language R/O 10
SMSInfo/Nickname Biller Nickname R/O 50
SMSInfo/BillerName Biller Name in English R/O 50
SMSInfo/BillerNameAr Biller Name in Arabic R/O 50

 

Response
Field Description Always
StatusCode Request status code Yes
StatusDesc Request status Yes
HostName Host name No
HostStatusCode Host request status code Yes
HostStatusDesc Host request status description Yes
RqUID Unique Request ID No
ClientDt Request time stamp No
LangPref Echo From Request Yes
GroupPayId Group payment ID Yes
RecordCount No of times BillDtls repeats Yes
PayRecordStatus B00000 -Success
10001 -Date must be Gregorian
12000 -Merchant is deactivated from Sadad
12001 -The specified Biller does not exist in the system
13000 -Account not found.
13006 -Your account has been disabled. Please contact the Administrator
30000 -Overpayment or underpayment is not allowed (When no overpayment, underpayment rule is defined and it fails the exact amount validation).
30006 -Over payment is not allowed ,etc:		 Yes
BankTrnNum Bank Payment Transaction Number for future reference Yes
SADADTrnNum SADAD payment transaction number for future reference Yes
CurrAmt Current Amount Yes
ProcessDate Transaction Date YYYY-MM-DDTHH:MI:SS Yes
BillingAcct Billing account number Yes
BillerID Biller ID Yes
ANBAcctNum ANB Account Number Debit Account Number Or Credit Card Number Yes
ANBAcctType ANB Account Type
1-Normal Account
2-Credit Card Account		 Yes

 

Inquiry

Invoice Inq

This service mostly will be used by esal billers.

 

Request
Fields Description R: Required
O:Optional
C:Conditional		 Length
Sequence Number Sequence Number R 50
LangPref Preferred Language R 10
InvoiceCode InvoiceCode you which you need to inquire. R 32
BillerId Biller Identification number: Pass SIH if you dont know. R 3
StartDt Start date for inquiring invoice. Format should be in YYYY-MMDDTHH: MM:SS O 19
EndDt End date for inquiring invoice. Format should be in YYYY-MMDDTHH: MM:SS O 19
MinInqAmt Minimum Amount for inquiring invoice O 20
MaxInqAmt Maximum Amount for inquiring invoice O 20
SupplierName Inquire invoice for specific Supplier O 150
RecCtrlIn/MaxRecs Not applicable for this service. Always pass 1 R 2
RecCtrlIn/Offset Not applicable for this service. Always pass 0 O 150
AdditionalInfo/Key For future use O 50
AdditionalInfo/Value For future use O 50
RecCtrlIn/Offset For first request, value must be 1. For subsequent requests, need to carry the value in /Body/RecCtrlOut/Offset returned in the previous response. R 54

 

Response
Field Description Always
StatusCode Request status code Yes
StatusDesc Request status Yes
HostName Host name No
HostStatusCode Host request status code Yes
HostStatusDesc Host request status description Yes
RqUID Unique Request ID No
ClientDt Request time stamp No
Offset Page Yes
SentRecs Number of returned records Yes
Completed Completion flag Yes
BillCategory The BillCategory element is populated with the Invoice Category. The values currently defined are EXACT and PARTIAL Yes InvoiceCode Invoice code Yes
InvoiceNum Invoice number Yes
BillerID Biller identification number Yes
BillerName Biller Name Yes
BuyerName Buyer Name Yes
AmtDue Due Amount for the invoice provided Yes
DueDt SADAD Invoice Due Date. Format is YYYY-MM-DDTHH:MM:SS Yes
BillType Type of invoice Yes
Locale Invoice Current bill status locale Yes
Value Invoice Current bill status value Yes
MinPmtAmt Minimum Payment amount for the invoice Yes
MaxPmtAmt Maximum Payment amount for the invoice Yes
AdditionalInfo Additional Info Aggregate Yes

 

Transaction Inq

This service can used to inquire about the transactions status of all requests (MOI/Non-MOI or SADAD Billers). You can utilize this service to make sure about the payment status of request in case of Timeout or any other incomplete request status. Thisservice can be used to inquire about esal billers.

 

Request
Fields Description R: Required
O:Optional
C:Conditional		 Length
TrnsType 1 – All
2 – Payment
3 – Payment Reversal
4 – Refund		 R 1
FromDt YYYY-MM-DD O 10
ToDt YYYY-MM-DD O 10
AcctNum ANB account number R 20
AcctType 1. Normal Account 2. Credit Account Account O 1
ANBTrnsNum This number could the payment number or reversal number O 20

 

Response
Field Description Always
StatusCode Request status code Yes
StatusDesc Request status Yes
HostName Host name No
HostStatusCode Host request status code Yes
HostStatusDesc Host request status description Yes
RqUID Unique Request ID No
ClientDt Request time stamp No
TimeStamp YYYY-MM-DDTHH:MM:SS Yes
RecordCount Number of times SadadTrnsDtls repeat Yes
SadadTrnNum SADAD payment transaction number Yes
BankTrnNum Bank Payment Transaction Number Yes
ProcessDate YYYY-MM-DDTHH:MM:SS Yes
TrnsType 1 – All
2 – Payment
3 – Payment Reversal
4 – Refund		 Yes
BillerId Biller Id Yes
SubscribeNum Subscriber Billing account of the bill Yes
ValDt YYYY-MM-DDTHH:MM:SS Yes
Amount Amount Yes
PayStatusCode Payment Status in SADAD Yes
ANBAcctNum ANB Account Number Yes
BranchCode ANB Branch code Yes
MOISvcCode MOI service code Yes

 

Bill Pay Advice (Govt/MOI Bill Payment)

In this bill payment section we have two services. Bill pay advice and Invoice bill payment. Both these services have different functionality as explained in each service.

 

 

Bill Pay Advice

This service is used to initiate the actual payment of MOI services. You need to call MOI Fee Inquiry before you calling this service. Once you have call the MOI Fee Inquiry then you can call this service by getting some fields from the response.

 

You need to copy these fields from MOI Fee Inquiry response and pass in this Bill Pay Advice service:

  1. GroupPayId.
  2. SADADTrnNum.

 

Flow:

 

Request
Fields Description R: Required
O:Optional
C:Conditional		 Length
Sequence Number Sequence Number R 50
LangPref Preferred Language R 10
ProxyPOI/POINum Customer ID number. This is mandatory only for branch channel, other than branch it is space O 10
ProxyPOI/POIType Customer ID Type. This is mandatory only for branch channel, other than branch it is space O 10
GroupPayId Mandatory for MOI payment R 36
BillPayAdviceInfo/RecordCount Number of times BillPayAdviseDtls repeats R 3
BillPayAdviceInfo/BillPayAdviceDtls/ANBAcctNum Debit Account Number or Credit Card Number R 20
BillPayAdviceInfo/BillPayAdviceDtls/ANBAcctType ANB Account type
1-Normal Account
2-Credit Card Account		 R 1
BillPayAdviceInfo/BillPayAdviceDtls/CardExpDt Credit card expiration date, with format (yyyyMMdd). This field is mandatory for credit card account only R 10
BillPayAdviceInfo/BillPayAdviceDtls/SADADTrnNum Returned by SADAD in PVALRS and sent in PADVRQ R 32
/Body/BillPayAdviceInfo/BillPayAdviceDtls/POI/POINum Customer official Id is a unique identifier for a bill-paying entity, including people and companies. This field is mandatory for non-branch channel and optional for branch R/O 50
/Body/BillPayAdviceInfo/BillPayAdviceDtls/POI/POIType Customer ID Type This field is mandatory for non-branch channel and optional for branch. Mapping with A4SADAD.
Passport Number-PAS
BTELLER-BTL
Business ID-BIS
Copy of Iqama-IQA
National ID-NAT		 R/O 50
BillPayAdviceInfo/BillPayAdviceDtls/PmtStatusCode Payment Satatus Code PmtTransf – The payment was successfully completed Or, if a multi-payment advice failed, the corresponding payment record was not the cause of that failure. PmtNotTransf – The payment was not successfully completed. Or, if a multi-payment advice failed, the corresponding payment was at least one of the causes for that failure.
Use-case: When you do a MOI fee inquiry, then its good to call the bill pay advice against that MOI inquiry. After doing the MOI inquiry, if you want to make payment then pass this field as PmtTransf otherwise if you don’t want to make payment then call the bill pay advice with this field as PmtNotTransf. In case you do a MOI inquiry and dont call the bill pay advice, this field will be marked as PmtNotTransf automatically after one day. Dont need to take input from customer.		 R 12
BillPayAdviceInfo/BillPayAdviceDtls/TrnAmt Transaction Amount R 19
BillPayAdviceInfo/BillPayAdviceDtls/BillProsDt Bill Posting Date:
Lets you call the service today but you want to make the actual payment on some future day, then you need to input that day datetime here.		 R 19
BillPayAdviceInfo/BillPayAdviceDtls/BillNum Bill Number. This field is optional if billing account is provided, and not used in case of advising Fee inquiry payment O 19
BillPayAdviceInfo/BillPayAdviceDtls/BillingAcct Subscriber Number. This field is optional if bill number is provided, and not used in case of advising Fee inquiry payment O 19
/BillPayAdviceInfo/BillPayAdviceDtls/BillerID Biller ID
25- STC
002 – SCECO
003 – NCCI
004 – Marafiq
005 – Mobily
OR MOI biller code etc…		 R 3
BillPayAdviceInfo/BillPayAdviceDtls/ServiceCode This represents the service offered by ministry of interior to the customers:
001 -Extend Visitor Visa
002 -Issue New Iqama
003 -Renew Iqama
004 -Exit Re-entry Visa ( Single)
005 -Exit Re-entry Visa (Multiple)
006 -Visa Cancellation
007 -Transfer of Sponsorship
008 -Replace Iqama
009 -Transfer Dependant to be Head of Household
010 -Transfer Head of Household to be Dependant
011 -Transfer Dependant to a New Head of Household
012 -Change of Occupation ,
013 -Dependants Entry visa Fee Collection
14 -Adding Dependent born inside Saudi Arabia after one Year from his Date Of Birth
015 -Dependent Separation
016 -Issue New Iqama for a Citizen’s wife
017 -Birth Registration
018 -Death Registration
019 -Marriage Registration
020 -Divorce Registration
021 -Lost ID Cards Registration
022 -Issue License
023 -Issue License from Old License
024 -Replace License
025 -Renew License
026 -Renew Vehicle Registration
027 -Transfer Owner
028 -Re-issue Registration Card
029 -Re-issue License Plate ( 1 plate only)
030 -Export Vehicle
031 -Exchange Plates by Owner
032 -Exchange Plates Not by Owner
033 -Sequence Number Inquiry 1 (New License Plates Only)
034 -Sequence Number Inquiry 2 (New License Plates Only)
035 -Issue New Passport
036 -Re-issue Passport
037 -Renew Passport
038 -Family Visa
039 -Labor Visa
040 -Traffic Violations
041 - Query traffic violations by violation ID
042 - Register Vehicle
043 - Re-import vehicle
044 - Transfer Plates (Give plates to registered vehicle without plates)
045 - Transfer Plates (changing current vehicle plates)
046 - Pay All Deportation Sentences Installments
047 - Pay One Deportation Sentence Installment
048 - Runaway Cancelation
049 - Transform Vehicle Into Junk
050 - Pay a Deportation Travel Ticket Fee
052 - Lost passport Fine
053 - Issue Family Card
054 - Other Fees and Fines
055 - Pay all Violations’ Fines
056 - Pay One Civil Defense Violations’ Fine
057 - Extend Exit Reentry Visa Duration
058 - Associate Fees for a Specific Associate Service ID
059 - Associate Fees for All Registered Associates on the Head of Household Iqama Service
060- Pay by Violator ID for a Specific Category		 R 3
/BillPayAdviceInfo/BillPayAdviceDtls/BenId the beneficiary is the actual customer for the biller for which you going to pay the fee. R 32
/BillPayAdviceInfo/BillPayAdviceDtls/BenfIdType The beneficiary ID Type: i.e Iqama, national ID etc R 3
BillPayAdviceInfo/BillPayAdviceDtls/BenName Beneficiary Name R/O 128
BillPayAdviceInfo/BillPayAdviceDtls/SponsorId The Id of the Sponsor of Visa to the customer R/O 10
BillPayAdviceInfo/BillPayAdviceDtls/IqamaDuration This value contains the duration of Iqama . In multiples of 3 till max 300. This value contains the duration of Iqama (In years 1,2,3 mandatory and Applicable for only 009 -Transfer Dependant to be Head of Household service R/O 5
BillPayAdviceInfo/BillPayAdviceDtls/JobCategory This represents the type of job the customer is applying R/O 2
BillPayAdviceInfo/BillPayAdviceDtls/DependentCount The value of Number of Dependents of the customer R/O 5
BillPayAdviceInfo/BillPayAdviceDtls/VisaCount This is the value of number of visas based on the number of dependents or employees, R/O 2
BillPayAdviceInfo/BillPayAdviceDtls/VisaType This represents the type of visa the customer is applying R/O 2
BillPayAdviceInfo/BillPayAdviceDtls/VisaNum The Saudi visa number R/O 10
BillPayAdviceInfo/BillPayAdviceDtls/CitizenId This is the Id value of the Saudi citizens R/O 10
BillPayAdviceInfo/BillPayAdviceDtls/EventDt This value is the actual date of the incident that had happened which should be reported to the government: (YYYY-MM-DDTHH:MM:SS) R/O 19
BillPayAdviceInfo/BillPayAdviceDtls/LicenseType This represents the type of license the customer wants to apply R/O 2
BillPayAdviceInfo/BillPayAdviceDtls/VehicleSeqNum This is the unique number of the vehicle provided by the manufacturer R/O 10
BillPayAdviceInfo/BillPayAdviceDtls/NewOwnerId This is the Id of the person to whom the vehicle registration will be transferred R/O 10
BillPayAdviceInfo/BillPayAdviceDtls/ViolationId This is the numeric value present in the license plate:
1-Normal Account
2-Credit Card Account		 R/O 10
BillPayAdviceInfo/BillPayAdviceDtls/BodyType This represents the vehicle body type:Yyyy-MM-dd R/O 3
BillPayAdviceInfo/BillPayAdviceDtls/NewRegType This represents the new type of vehicle registration R/O 2
BillPayAdviceInfo/BillPayAdviceDtls/PassportType This represents the type of passport the customer wants to apply R/O 2
BillPayAdviceInfo/BillPayAdviceDtls/VehCustCardNum Vehicle custom card number R/O 10
BillPayAdviceInfo/BillPayAdviceDtls/MultiCurrency Multi Currency Flag
Y-the payment is using multi currency transaction
N-the payment is not using multi currency transaction:
Y-the payment is using multi currency transaction
N-the payment is not using multi currency transaction		   1
BillPayAdviceInfo/BillPayAdviceDtls/Currency The currency used in the multi currency payment R/O 3
BillPayAdviceInfo/BillPayAdviceDtls/ExRate Exchange rate value R/O 18
BillPayAdviceInfo/BillPayAdviceDtls/LicenseDuration This value contains the duration of license in years Mandatory for the following services:
022 –Issue License
023 –Issue License For Old
025 –Renew License
Possible Values:
01
02
05		 R/O 5
BillPayAdviceInfo/BillPayAdviceDtls/IssuingEntityID Issuing Entity ID(This field is applicable to service 060) R/O 8
BillPayAdviceInfo/BillPayAdviceDtls/ViolationCategoryID Violation Category ID(This field is applicable to service 060) R/O 4
SMSInfo/MobileNum Customer mobile number R/O 20
SMSInfo/SMSPreferLang Customer SMS preferred language R/O 10
SMSInfo/Nickname Biller Nickname R/O 50
SMSInfo/BillerName Biller Name in English R/O 50
SMSInfo/BillerNameAr Biller Name in Arabic R/O 50

 

Response
Field Description Always
StatusCode Request status code Yes
StatusDesc Request status Yes
HostName Host name No
HostStatusCode Host request status code Yes
HostStatusDesc Host request status description Yes
RqUID Unique Request ID No
ClientDt Request time stamp No
GroupPayId Mandatory for MOI payment. Sent only if /MsgRqHdr/Version < 2.0 Yes
RecordCount Number of times BillPayAdviseData repeats Yes
PayRecordStatus 00000 –Success
10001 –Date must be Gregorian
12000 –Merchant is deactivated from Sadad
12001 –The specified Biller does not exist in the system
13000 –Account not found.
13006 –Your account has been disabled. Please contact the Administrator
30000 –Overpayment or underpayment is not allowed (When no overpayment, underpayment rule is defined and it fails the exact amount validation).
30006 –Over payment is not allowed ,etc		 Yes
BankTrnNum ANB payment transaction number Yes
SADADTrnNum SADAD payment transaction number Yes
PayAdviceStatus PmtTransf – The payment was successfully completed Or, if a multi-payment advice failed, the corresponding payment record was not the cause of that failure. PmtNotTransf – The payment was not successfully completed. Or, if a multi-payment advice failed, the corresponding payment was at least one of the causes for that failure. Yes

 

Invoice Bill Payment

This service is used to pay bill using bill invoice number provided by relevant biller. Most of the time it will used for ESAL billers.

 

Request
Fields Description R: Required
O:Optional
C:Conditional		 Length
Sequence Number Sequence Number R 50
LangPref Preferred Language R 10
POI/POINum Customer official Id is a unique identifier for a bill paying entity, including people and companies. R 32
POI/POIType Customer Official ID type This field is mandatory for non-branch channel and optional for branch. Mapping with A4SADAD. Passport Number-PAS BTELLER-BTL Business ID-BIS Copy of Iqama-IQA National ID-NAT. Proof of identity type:
National ID
Copy of Iqama
EXPAT ID CARD
Business ID
Account ID
SADAD ID
Bank Teller Number
Bank Employee Number
SADAD Employee Number
Biller Employee Number
Passport Number		 O 50
BankAcctInfo/BankAcctNum Customer Bank Account Number R 20
BankAcctInfo/BankAcctType Account Type:
0:Normal Account
1:Credit Card Account		 R 15
BankAcctInfo/CardExpDt Card Expiry date YYYY-MM-DDTHH:MM:SS O 19
BankAcctInfo/MultiCurFlg 1:Yes
2:No		 O 1
BankAcctInfo/CurCode The currency used in the multi-currency payment. Default SAR O 3
BankAcctInfo/ExRate Exchange Rate. Default 1 O 1
PmtInfo/CurAmt Payment Amount R 12
PmtInfo/PrcDt Transaction date( YYYY-MMDDTHH:MM:SS) R 19
PmtInfo/DueDt Bill due date( YYYY-MMDDTHH:MM:SS) R 19
PmtInfo/BillCycle Bill cycle Number O 32
PmtInfo/BillNum Bill Number O 32
PmtInfo/AcctIdInfo /BillingAcct Billing Account R 32
PmtInfo/AcctIdInfo /BillerId Biller Code O 32
PmtInfo/AcctIdInfo /BillerName Biller Name O 128
PmtInfo/DistCode Bank District Code, Current value: ARNBSARI R 10
PmtInfo/BranchCode Bank Branch code
Current value: 0170		 R 10
PmtInfo/PmtMethod Payment method R 32
PmtInfo/PmtType Payment method type:
POST-Postpaid
RCHG-Recharge
RNEW-Renewal
RDEP-Roaming Deposit
RADV-Advance Payment for roaming		 R 04
PmtInfo/ChkDigit Check Digit O 2
PmtInfo/SvcType Service Type:
CIP -Customer Initiated Payment ELCT -Electricity PHON -Phone
GSM -Mobile phone service – a subtype of PHON
LLIN -Land Line phone service – a subtype of PHON INSR -Insurance BKSV -Bank Service GOVT Government Service
MED -Medical
CCRD -Credit Card UTIL -Utility
PCIN -Personal Computer Payment Installment
EXAM -University Exam Fees		 R 50
PmtInfo/PmtRefInfo Payment Reference information(The value coming from biller in the Bill Inquiry) /td> O 128
PmtInfo/IncInfo/IncPmtRange Payment Range
1:True
2:False		 R 1
PmtInfo/BenfIdInfo/BenfId Beneficiary ID R 32
PmtInfo/BenfIdInf/BenfIdType Proof of identity type:
National ID
Copy of Iqama
EXPAT ID CARD
Business ID
Account ID
SADAD ID
Bank Teller Number
Bank Employee Number
SADAD Employee Number
Biller Employee Number
Passport Number		 R 50
PmtInfo/AdditionalInfo/Key Key_Type O 50
PmtInfo/AdditionalInfo/Value Desc_type O 50

 

Response
Field Description Always
StatusCode Request status code Yes
StatusDesc Request status Yes
HostName Host name No
HostStatusCode Host request status code Yes
HostStatusDesc Host request status description Yes
RqUID Unique Request ID No
ClientDt Request time stamp No
POINum Customer Id Yes

 

Initiate Refund

To initiate refund here is the process.

  1. You need to generate refund id using Refund I Generation service.

  2. You will initiate the refund using refund inquiry service

  3. You can check your refund request status using refund status service

 

Flow:

 

Refund Status

This service is used to get Refund Status from SADAD by providing Refund ID.

 

Query Params
Fields Description R: Required
O:Optional
C:Conditional		 Length
Sequence Number Sequence Number R 50
RefundId Refund ID R 18

 

Response
Field Description Always
StatusCode Request status code Yes
StatusDesc Request status Yes
HostName Host name No
HostStatusCode Host request status code Yes
HostStatusDesc Host request status description Yes
RqUID Unique Request ID No
ClientDt Request time stamp No
RefundId Refund ID Yes
TimeStamp YYYY-MM-DDTHH:MM:SS Yes
RefundStatus 0- Processed (Amount Refunded)
1- Approved (Refund request accepted and will be processed)
2- Rejected (Request rejected)
3- Pending (Represents that the refund is not rejected by the biller but will update the status as rejected or accepted during refund upload)
4- Not found (Request details not found)
5- Already_Reconciled (Already refunded)
6- UnReconciled (A reconciliation error has occurred for the associated refund)
7- Processing_Failed
8- Timeout (Represents that the bank has not adviced refund in the expected timeframe)
9- Duplicate (Duplicate Refund in Bank)		 Yes

 

Refund Inquiry (Initiate Refund)

This service is used to get refund information from SADAD.

 

Request
Fields Description R: Required
O:Optional
C:Conditional		 Length
Sequence Number Sequence Number R 50
LangPref Preferred Language R 10
RefundId Refund ID R 35
BillerId 001- STC
002 – SCECO
003 - NCCI
004 – Marafiq
005 – Mobily etc…		 R 3
BenfId the beneficiary is the actual customer for this service, for “MOI Motor Vehicle biller” send the “vehicle sequence number” or “Vehicle Custom Card Number” depend on the service R 32
BenfIdType the beneficiary Type is the actual customer for this service, , If the Beneficiary Id is not National ID, Iqama ID, Business ID, or Passport Id, then this R 3
ANBAcctNum BankAcct represents the beneficiary account (debit account) or Credit Card Number where the amount will be transferred R 20
ANBAcctType 1-Normal Account
2-Credit Card Account		 R 1
CardExpDt YYYY-MM-DD R/O 10
POI/POINum Proof of identity number R 50
POI/POIType Proof of identity type
Passport Number
BTELLER
Business ID
Copy of Iqama
National ID		 R 50
ServiceCode This represents the service offered by ministry of interior to the customers R 3

 

Response
Field Description Always
StatusCode Request status code Yes
StatusDesc Request status Yes
HostName Host name No
HostStatusCode Host request status code Yes
HostStatusDesc Host request status description Yes
RqUID Unique Request ID No
ClientDt Request time stamp No
LangPref ARABIC, ENGLISH Yes
RefundId Refund Id is a unique Identification number assigned to individual refunds. Yes
BillerId MOI Biller ID Yes
BankAcctNum BankAcct is a savings or current bank account of the beneficiary (debit account) where the refund amount will be transferred Yes
ANBAcctType 1-Normal Account
2-Credit Card Account		 Yes
BenfId the beneficiary is the actual customer for the biller Yes
BenfIdType the beneficiary Type is the actual customer for the biller Yes
POINum Customer official Id is a unique identifier for a bill-paying entity, including people and companies Yes
POIType Proof of identity type For defined values refer to section Id Type in MB LOV doc
Proof of identity type
Passport Number
BTELLER
Business ID
Copy of Iqama National ID		 Yes
RefundExpDate Refund Expiration Date YYYY-MM-DDTHH:MM:SS Yes
RefundStatusCode Represent Refund status in SADAD
Accepted - Represents the requested refund is accepted by the biller
Already_Reconciled - Refund already reconciled
Duplicate - Duplicate Refund in Bank
Mismatch - Either the refund data in SRL or state of refund is different than the one in SADAD
Not_In_Bank - Refund not known to Bank
Not_In_Sadad - Refund does not exist in SADAD
Pending - Represents that the refund is not rejected by the biller but will update the status as rejected or accepted during refund upload
Processed - Represents that the refund has been processed and the customer has received the funds
Processing_Failed - Indicates that funds transfer from the SRA to the beneficiaries‟ account has failed
Reconciled - Refund has exactly matched between systems
Timeout - Represents that the bank has not adviced refund in the expected timeframe.
UnReconciled - A reconciliation error has occurred for the associated refund
Rejected - Represents refund is rejected by the biller		 Yes
ServiceCode This represents the service offered by ministry of interior to the customers Yes

 

Billers List

Pvt Billers

Billers private endpoint used to get private biller details.

 

Response
Field Description Always
BillerCode Specific biller code Yes
Id Unique Id Yes
BillerCategoryId Biller category id No
ArabicDescription Arabic description Yes
EnglishDescription English description Yes
AllowPartialPayment Partial payment Yes
MinimumPartialPayment Minimum payment limit Yes

 

MOI/Govt Billers

Billers private endpoint used to get government biller details.

 

Response
Field Description Always
StatusCode Request status code Yes
StatusDesc Request status Yes
HostName Host name No
HostStatusCode Host request status code Yes
HostStatusDesc Host request status description Yes
RqUID Unique Request ID No
ClientDt Request time stamp No
TimeStamp YYYY-MM-DDTHH:MM:SS Yes
RefundId Refund Id (ANB swift code with 10 digits) Yes

 

API Documentation