Salary advances

The Advances endpoints let you manage salary advances — early access to earned wages, repaid from the employee’s upcoming pay.

Salary advance is an add-on. The company must have it enabled — otherwise every /v1/advances* call returns 403 MODULE_NOT_ENABLED (a company admin enables it in Settings → Modules). Calls need the matching scope: advances:read for reads, advances:write for writes.

Approving an advance disburses real money from the company wallet to the employee. For that reason, advance writes are not available with a kua_test_ key (400 TEST_MODE_UNSUPPORTED) — use a live key, and gate the advances:write scope carefully.

List advances

Optionally filter by employeeId:

curl "https://api.kuahr.com/v1/advances?employeeId=b2c3…" \
  -H "X-Api-Key: kua_live_your_key_here"

const advances = await kua.advances.list({ employeeId: "b2c3…" });

advances = kua.advances.list(employee_id="b2c3…")

Amounts are in minor units (e.g. kobo) — 5000000 is ₦50,000.

Request an advance

Starts a Pending advance for an employee (advances:write):

curl https://api.kuahr.com/v1/advances \
  -X POST -H "X-Api-Key: kua_live_your_key_here" -H "Content-Type: application/json" \
  -d '{ "employeeId": "b2c3…", "amountMinor": 5000000, "termMonths": 3 }'

const advance = await kua.advances.request({
  employeeId: "b2c3…",
  amountMinor: 5_000_000,
  termMonths: 3,
});

advance = kua.advances.request(employee_id="b2c3…", amount_minor=5_000_000, term_months=3)

An employee can have only one open advance at a time.

Approve or reject

Approving disburses funds and builds the repayment schedule; rejecting cancels the request:

curl -X POST https://api.kuahr.com/v1/advances/{id}/approve -H "X-Api-Key: kua_live_your_key_here"
curl -X POST https://api.kuahr.com/v1/advances/{id}/reject  -H "X-Api-Key: kua_live_your_key_here"

await kua.advances.approve(advance.id); // disburses money
await kua.advances.reject(advance.id);

kua.advances.approve(advance.id)  # disburses money
kua.advances.reject(advance.id)

Events

React to the advance lifecycle via webhooks: salary_advance.requested, salary_advance.approved, salary_advance.rejected.

​List advances

​Request an advance

​Approve or reject

​Events

List advances

Request an advance

Approve or reject

Events