PayrollTracking
Batch Tracking
Monitor batch progress in real time and inspect per-recipient payout status, including failure reasons and completion timestamps.
Get batch progress
Retrieve the overall status and progress counters for a payroll batch.
GET
/payroll/batches/{id}Get the current status and progress of a payroll batch.
curl https://wallet.e-mazad.store/api/v1/payroll/batches/batch_abc123 \
-H "Authorization: Bearer sk_sandbox_..."Polling recommendation
For large batches, poll the batch status every 5-10 seconds. Alternatively, listen for the
payroll.batch.completed webhook event.Per-recipient status
Drill into individual recipient payouts to see which succeeded and which failed.
GET
/payroll/batches/{id}/recipientsList all recipients in a batch with their individual payout status.
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
| status | string | optional | Filter by recipient status: "completed", "failed", or "pending". |
| page | integer | optional | Page number. Default: 1. |
| per_page | integer | optional | Results per page (max 100). Default: 50. |
curl https://wallet.e-mazad.store/api/v1/payroll/batches/batch_abc123/recipients \
-H "Authorization: Bearer sk_sandbox_..."Failure reasons
When a recipient payout fails, the failure_reason field indicates what went wrong. Use this to diagnose and retry if appropriate.
| Reason code | Description |
|---|---|
| insufficient_balance | Recipient wallet could not receive funds due to internal limits. |
| recipient_not_found | The customer_id does not exist or has been deleted. |
| wallet_suspended | The recipient wallet is suspended or frozen by compliance. |
| currency_mismatch | Recipient wallet does not support the batch currency. |
| amount_below_minimum | The payout amount is below the minimum transfer threshold. |
| amount_above_maximum | The payout amount exceeds the per-transfer maximum. |
| duplicate_recipient | The same customer_id appeared more than once in the batch. |
| internal_error | An unexpected error occurred. The amount has been refunded to merchant. |
Handling failures
Failed payout amounts are automatically refunded to your merchant wallet. To retry failed recipients, create a new batch containing only the failed recipients after resolving the underlying issue.
Webhook events
Subscribe to these events to track batch progress without polling.
| Event | Trigger |
|---|---|
| payroll.batch.processing | Batch submitted and funds reserved |
| payroll.batch.completed | All recipients processed successfully |
| payroll.batch.partially_completed | Batch finished with some failures |
| payroll.batch.failed | Entire batch failed (e.g., insufficient balance) |
| payroll.recipient.completed | Individual recipient payout succeeded |
| payroll.recipient.failed | Individual recipient payout failed |