Close, write off, or restructure a loan
Use the Collections API to send changes from your lending system.
Read current state with `GET /api/v1/collections/clients/collection/{collection}/lifecycle`.
Record a change with `POST /api/v1/collections/clients/collection/{collection}/lifecycle/events`.
Send a unique event_id for each change. Replaying the same event returns the current snapshot. Reusing the ID with different data returns HTTP 409. If a debit is processing, wait for it to settle before retrying the lifecycle event. Send positive integer amounts in minor units. For NGN, 10000 means ₦100.
| Event type | Additional required fields | Effect |
|---|---|---|
payment | instalment_id, amount_minor | Records a payment received elsewhere and reduces the remaining instalment balance. A written-off collection can still receive this event. |
discount | instalment_id, amount_minor | Reduces what is owed on the instalment. |
partial_write_off | instalment_id, amount_minor | Reduces what is owed on the instalment and records the adjustment as a write-off. |
fee | instalment_id, amount_minor, fee_type | Adds an institution-specified fee to the instalment. |
write_off | No additional required fields | Sets written_off, keeps the remaining balance on record, and sets the collectible amount to zero. |
close | No additional required fields | Closes an active or written-off collection. Record any payment or adjustment that should change the balance separately. |
early_close | No additional required fields | Closes an active collection through an early-close event. |
restructure | replacement_reference | Marks the old collection as restructured and records the replacement reference. Create and track the replacement collection separately. |
You may also send reason and occurred_at. A payment, discount, or partial write-off that exceeds the remaining instalment balance is rejected. A payment after write-off reduces the recorded balance while the collection remains written off.
curl --request POST \
"$COLLECTIONS_BASE_URL/api/v1/collections/clients/collection/$COLLECTION_ID/lifecycle/events" \
--header "Authorization: Bearer $COLLECTIONS_API_KEY" \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data '{"event_id":"loan-demo-001-write-off","type":"write_off","reason":"Full write-off approved"}'The response wraps the current state in data. Read status, remaining_amount_minor, collectible_amount_minor, and next_debit. When present, next_debit includes the instalment ID, its remaining amount, and the earliest eligible date. Closing, early closing, write-off, and restructuring make the old collection ineligible for further debit attempts. Check bureau submission outcomes separately.