Operate payment jobs

Workbench accepts payment jobs and delegates durable process state to the settlement domain. Job acceptance is not settlement completion.

Submit a job

curl -sS -X POST https://workbench.mavula.dev/api/jobs \
  -H "Authorization: Bearer $MAVULA_ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: bfe8b575-2137-4a86-a210-cc2182130aed' \
  -H 'X-Correlation-ID: fd662f62-19c7-4f92-941f-64667437e6f9' \
  -d '{"queue":"payments","type":"PAYMENT_CAPTURE","max_attempts":3,"payload":{"idempotency_key":"payment_capture_20260715_001","correlation_id":"fd662f62-19c7-4f92-941f-64667437e6f9","rail":"mpesa","amount":{"currency":"MZN","valueMinor":250000},"payer":{"accountRef":"customer_001","phoneNumber":"+258840000001"},"payee":{"accountRef":"merchant_001"}}}'

Persist the returned job identifier and poll the status resource:

curl -sS https://workbench.mavula.dev/api/jobs/JOB_ID \
  -H "Authorization: Bearer $MAVULA_ACCESS_TOKEN"

Operational states

State	Meaning	Client action
Accepted or queued	Work is durable and awaiting execution	Poll with bounded backoff
Active	Provider interaction or reconciliation is in progress	Continue polling
Completed	Process reached its terminal successful state	Reconcile the resulting domain state
Failed	Retry policy was exhausted or input cannot proceed	Read failure details; correct before resubmission
Expired	Process exceeded its permitted execution window	Investigate provider state before retrying
Compensation required	Automated completion is unsafe	Escalate to an authorized operator

Do not infer a ledger posting from a payment process state. Ledger Core remains the owner of financial postings and invariants.