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 typeAdditional required fieldsEffect
paymentinstalment_id, amount_minorRecords a payment received elsewhere and reduces the remaining instalment balance. A written-off collection can still receive this event.
discountinstalment_id, amount_minorReduces what is owed on the instalment.
partial_write_offinstalment_id, amount_minorReduces what is owed on the instalment and records the adjustment as a write-off.
feeinstalment_id, amount_minor, fee_typeAdds an institution-specified fee to the instalment.
write_offNo additional required fieldsSets written_off, keeps the remaining balance on record, and sets the collectible amount to zero.
closeNo additional required fieldsCloses an active or written-off collection. Record any payment or adjustment that should change the balance separately.
early_closeNo additional required fieldsCloses an active collection through an early-close event.
restructurereplacement_referenceMarks 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.

bash
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.