PayrollStatus
GET
https://test.api.neotek.sa/b2b-unified/v1/payroll/status/{payrollReference}Sandbox URL · in Production call https://api.neotek.sa
Where the batch has got to, and the result for each employee in it.
Path parameters:
| Parameter | Required | Description |
|---|---|---|
payrollReference | Required | the reference from SubmitPayrollBatch, exactly as returned |
Query parameters:
| Parameter | Required | Description |
|---|---|---|
bankCode | Required | which bank executed the batch: RJHISARI or ARNBSARI |
Headers:
| Parameter | Required | Description |
|---|---|---|
authorization | Required | Bearer <ACCESS_TOKEN> |
cURL
curl -G 'https://test.api.neotek.sa/b2b-unified/v1/payroll/status/{payrollReference}' \ --header 'authorization: Bearer <ACCESS_TOKEN>' \ -d 'bankCode=ARNBSARI'Polling: banks take 10 to 30 minutes. Start at 10 minutes and retry every 2 to 5. Still PAYMENT_STATUS_IN_PROGRESS after 30 minutes means contacting support.
Response — while processing, payments is empty
JSON
{ "success": true, "code": "SUCCESS", "message": "Payroll is being processed, please retry shortly", "payrollReference": "c20423c3-5df2-465b-9dd2-ca1614aa9463", "paymentStatus": "PAYMENT_STATUS_IN_PROGRESS", "statusDescription": "Payroll batch is being processed", "payments": []}Response — once complete, one entry per employee
JSON
{ "success": true, "code": "SUCCESS", "message": "Payroll status retrieved successfully", "payrollReference": "c20423c3-5df2-465b-9dd2-ca1614aa9463", "paymentStatus": "PAYMENT_STATUS_COMPLETED", "statusDescription": "Payroll batch processed successfully", "payments": [ { "employeeId": "2019092502", "bankPaymentReference": "OB20260420123456", "paymentStatus": "PAYMENT_STATUS_COMPLETED", "statusDescription": "Processed Successfully" }, { "employeeId": "1098765432", "bankPaymentReference": "OB20260420123457", "paymentStatus": "PAYMENT_STATUS_FAILED", "statusDescription": "Beneficiary bank rejected: invalid BIC code" } ]}Partial success is the norm, not an edge case. A batch-level PAYMENT_STATUS_COMPLETED means the bank finished processing — not that every salary landed. The example above completed with one employee paid and one rejected. Always read the per-employee array.
Errors — each failure carries an error category and a specific code
| Status | Codes | Cause |
|---|---|---|
400 ERROR_CATEGORY_VALIDATION_FAILED | INVALID_BANK_CODE, INVALID_REFERENCE | Unknown bankCode, or a malformed reference |
401 ERROR_CATEGORY_AUTH_FAILED | AUTH_FAILED, CREDENTIALS_NOT_FOUND, UNAUTHORIZED | Token missing or expired, or no vault credentials for your app with that bank |
404 ERROR_CATEGORY_NOT_FOUND | NOT_FOUND | No batch matches that payrollReference at that bank |
500 ERROR_CATEGORY_SYSTEM_FAILURE | SYSTEM_ERROR, INTERNAL_ERROR | Gateway-side failure |
503 ERROR_CATEGORY_TEMPORARY_FAILURE | SERVICE_UNAVAILABLE, BANK_UNAVAILABLE, NETWORK_ERROR, NETWORK_TIMEOUT, REQUEST_TIMEOUT | Bank unreachable — retry with backoff |