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 Payroll 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.
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.