Payroll
Overview
Submit a WPS-compliant salary batch, poll it to completion, then download the bank-signed WPS file. Domestic only: beneficiary IBANs must be Saudi and BICs exactly 8 characters.
| Endpoint | Does |
|---|---|
| SubmitPayrollBatch | Sends the salary batch and returns a payrollReference |
| PayrollStatus | Reports batch progress and the result per employee |
| WPSFileDownload | Returns the signed WPS file for upload to Mudad |
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 B2B Unified Product in your chosen environment; it covers all seven B2B Unified products.
All seven B2B Unified products share one scope, b2b_unified. Request it once and the same token works here and on the other six; the Authentication page shows how.
Why the WPS file matters
Saudi labour law requires the WPS file to be filed at Mudad by the 10th of each month, and non-compliance costs SAR 3,000 per employee per month. This product delivers the bank-signed file ready to upload — that, rather than the payment itself, is what it exists for.
Working with it
Keep payrollReference exactly as returned. Do not parse or modify it; its format varies by bank. It is the key for both status and the WPS download.
Resubmitting is safe. The same employee set on the same payroll date produces a deterministic batch reference, so a repeat submission returns DUPLICATE_REFERENCE (409) rather than paying twice.
Partial success is normal. A batch-level PAYMENT_STATUS_COMPLETED means the bank finished processing, not that every salary landed. Always read the per-employee array.
Ready to build with Payroll?
Create a sandbox app, grab your credentials, and make your first call in minutes.