# 6. Track the payment status

After [setting a payroll for payment](https://code.salaxy.com/get-started/rest/set-for-payment.md), the payment progresses in the payment channel. You read the progress back from the API.

**The mechanism is polling.** There are no webhooks or push notifications today. Poll every few minutes — status changes follow banking-day events, not seconds.

## What to watch

- **The salary calculation is the unit of truth.** Each has its own `workflow.status`; one worker's payment succeeds or fails independently of the others.
- **The payroll status is derived.** It reaches `paymentSucceeded` only when *every* calculation has succeeded. Use it as a summary.

## Read endpoints

| Endpoint | Returns | Use for |
|---|---|---|
| `GET /v03/api/calculations/{id}` | The full calculation; read `workflow.status` | Following one salary |
| `GET /v03/api/calculations?$filter=status eq 'paymentStarted'` | A page of rows (`items`, `nextPageLink`) with `id`, `status`, `updatedAt` … | Sweeping all payments in flight in one query |
| `GET /v03/api/payroll/{id}` | The payroll; read `info.status` | The pay event as a whole |

The list query returns a page of rows:

```json
{
  "items": [
    { "id": "<calculation id>", "status": "paymentStarted", "updatedAt": "2025-08-29T10:15:00Z" }
  ],
  "nextPageLink": null
}
```

Match statuses in lowerCamelCase — `paymentSucceeded`, not `PaymentSucceeded`. For paging, follow `nextPageLink` and avoid `$top`; query syntax: [Queries and paging](https://code.salaxy.com/reference/queries.md).

## Statuses you will see

| Calculation status | Meaning | Final? |
|---|---|---|
| `paymentStarted` | Committed; the payment is in flight | No — keep polling |
| `paymentSucceeded` | The channel has confirmed the payment — **paid** | Yes |
| `paymentCanceled` | Cancelled by Salaxy after payment | Yes |
| `paymentError` | The payment failed — needs manual attention | Yes |
| `payrollDraft` or `draft` | Back to a draft: the payment was cancelled before it was paid. Edit and commit it again | Not a payment outcome — stop polling until it is committed again |

**Only `paymentSucceeded` means paid.** Do not infer payment from anything else — `paymentStarted` does not mean paid. Cancelling before payment is in [Payroll lifecycle and statuses](https://code.salaxy.com/integration/payroll-lifecycle.md#cancelling-a-payment).

**Customer funds account channels are the exception.** When Salaxy pays from a customer funds account, `paymentSucceeded` means Salaxy has received the employer's funds. Salaxy pays the worker after that. See [Payroll lifecycle and statuses](https://code.salaxy.com/integration/payroll-lifecycle.md#customer-funds-account-channels).

## A polling pattern

1. When you commit, record the calculation ids — or rely on the `status eq 'paymentStarted'` query.
2. Poll on a fixed interval, batching with the list query rather than one `GET` per calculation.
3. When a calculation reaches a final status, update your records and stop polling it.
4. **Alert on calculations that stay `paymentStarted`** longer than your channel normally takes. Salaxy never times a payment out — a stuck payment is yours to resolve: cancel and re-commit, or fix it in your own system.
5. Optionally read the payroll to close the pay event once `info.status` is `paymentSucceeded`.

## Check

- Polling uses the list query and follows `nextPageLink`.
- Only `paymentSucceeded` is treated as paid.
- An alert fires when a payment stays `paymentStarted` longer than your channel normally takes.

## Next

- [Payroll lifecycle and statuses](https://code.salaxy.com/integration/payroll-lifecycle.md) — the whole flow, including invoices and cancelling.
- The payment channel side — fetching invoices and reporting them paid, which drives these statuses: [Invoices and payments](https://code.salaxy.com/integration/invoices-and-payments.md).

← [5. Set for payment](https://code.salaxy.com/get-started/rest/set-for-payment.md)
