Run partner fees and record a payment

Before you start

• An active partner with termsFees are computed from the agreement in force. Open the guide
• Attributed loansThe run walks the loans attributed to each partner.
• A second userThe person who produced a draft cannot approve it.
• The partner idThe commands below call it $PARTNER_ID. It is the id returned when the partner was created.

Set your environment

Every request authenticates with HTTP Basic and names its tenant in a header. Set these once and the commands below work as written.

export LOKTA_API="https://default.lokta.tech"
export LOKTA_USER="your-username"
export LOKTA_PASS="your-password"

1. Run the fees for the period

The run walks every attributed loan, finds the agreement in force for its product and accrues each fee line for the days not yet covered. A rerun tops up late attributions instead of failing on overlap.

This is an example body. The reference does not list every field of this request yet, so treat the field names as placeholders and confirm them before you build.

curl -X POST "$LOKTA_API/lokta-lms/api/v1/fee-runs" \
  -u "$LOKTA_USER:$LOKTA_PASS" \
  -H "Tenant-Identifier: default" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "period_start": "2026-08-01",
    "period_end": "2026-08-31"
  }'

The response carries the fee run id. The next steps call it $RUN_ID.

2. Check what the run produced

Each accrual records the terms version, the line, the basis amount and the rate that produced it, so a figure raised today can still be explained later. Money is a decimal string, so do not parse it into a floating-point number.

curl -X GET "$LOKTA_API/lokta-lms/api/v1/fee-runs/$RUN_ID/accruals" \
  -u "$LOKTA_USER:$LOKTA_PASS" \
  -H "Tenant-Identifier: default"

3. Review the draft invoices

List the drafts, then open one with its evidence, the loan-level detail behind the figure.

curl -X GET "$LOKTA_API/lokta-lms/api/v1/draft-invoices" \
  -u "$LOKTA_USER:$LOKTA_PASS" \
  -H "Tenant-Identifier: default"

Note the id of the draft you want to approve. The next step calls it $DRAFT_ID.

4. Approve the draft

Approval creates the invoice and gives it a gap-free invoice number. The person who produced a draft cannot approve it: that returns 422 sourcing/checker_is_maker. A draft produced by the monthly batch is never refused for this.

A draft that was already decided returns 409 sourcing/draft_already_decided. To send a draft back, reject it with a reason instead.

curl -X POST "$LOKTA_API/lokta-lms/api/v1/draft-invoices/$DRAFT_ID/approval" \
  -u "$LOKTA_USER:$LOKTA_PASS" \
  -H "Tenant-Identifier: default" \
  -H "Idempotency-Key: $(uuidgen)"

5. Find the invoice

Approval created an invoice for the partner. List the partner's invoices to find it.

curl -X GET "$LOKTA_API/lokta-lms/api/v1/invoices?partner_id=$PARTNER_ID&status=approved" \
  -u "$LOKTA_USER:$LOKTA_PASS" \
  -H "Tenant-Identifier: default"

Note the id of the invoice. The next step calls it $INVOICE_ID.

6. Record the payment

Record what the invoice was settled by. A partial payment leaves the invoice unpaid, and an overpayment is refused with 422 sourcing/payment_exceeds_invoice_total.

If a payment was recorded wrongly, reverse it and record it again.

curl -X POST "$LOKTA_API/lokta-lms/api/v1/invoices/$INVOICE_ID/payments" \
  -u "$LOKTA_USER:$LOKTA_PASS" \
  -H "Tenant-Identifier: default" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "amount_paid": "26250.00"
  }'

Where to go next

Every request authenticates with HTTP Basic and carries a Tenant-Identifier header. See the conventions. Read this guide as Markdown.

This is the API reference for Lokta, the agentic loan servicing platform. Go to lokta.ai