Webhook Payload Documentation

This document outlines the structure and examples of the payloads received by three key webhooks in the Kona Finance system:

FacilityRepay Notification
PaymentAllocation Notification
RepaymentInstallment Status Change Notification

General Webhook Payload Structure

All webhook notifications include the following general structure:

{
  "created_at": "<ISO8601 timestamp>",
  "event": "<string>",
  "payload": { ... }
}

created_at: The timestamp when the webhook notification was created.
event: The type of event triggering the webhook (e.g., facility_repay_created).
payload: The specific details of the event.

1. FacilityRepay Notification

A FacilityRepay represents a payment received by our platform, signifying that a specific amount has been deposited into the designated bank account. Upon receiving the payment, a FacilityRepay object is created to initiate the repayment process. Subsequently, PaymentAllocation objects are generated to associate the FacilityRepay with corresponding RepaymentInstallments, ensuring that the repayment is accurately tracked and allocated.

Event Types:

facility_repay_created
facility_repay_status_changed

Payload Structure:

{
  "created_at": "<ISO8601 timestamp>",
  "event": "<string>",
  "payload": {
    "facility_repay_uuid": "<string>",
    "status": "<string>",
    "gross_amount": "<decimal as string>",
    "net_amount": "<decimal as string>",
    "receipt_status": "<string>"
  }
}

Example Payload:

{
  "created_at": "2025-01-03T10:00:00Z",
  "event": "facility_repay_created",
  "payload": {
    "facility_repay_uuid": "123e4567-e89b-12d3-a456-426614174000",
    "status": "pending",
    "gross_amount": "1000.00",
    "net_amount": "950.00",
    "receipt_status": "not_paid"
  }
}

The possible statuses are: pending, in_progress, completed and failed.

The possible receipt statuses are: not_paid, downloaded, sent and error.

2. PaymentAllocation Notification

Event Type:

payment_allocation_created

Payload Structure:

{
  "created_at": "<ISO8601 timestamp>",
  "event": "<string>",
  "payload": {
    "facility_repay_uuid": "<string>",
    "repayment_installment_uuid": "<string>",
    "amount_allocated": "<decimal as string>",
    "penalty_applied": "<decimal as string>"
  }
}

Example Payload:

{
  "created_at": "2025-01-03T10:05:00Z",
  "event": "payment_allocation_created",
  "payload": {
    "facility_repay_uuid": "123e4567-e89b-12d3-a456-426614174000",
    "repayment_installment_uuid": "456e7890-e89b-12d3-a456-426614174111",
    "amount_allocated": "500.00",
    "penalty_applied": "50.00"
  }
}

3. RepaymentInstallment Status Change Notification

Event Type:

installment_status_changed

Payload Structure:

{
  "created_at": "<ISO8601 timestamp>",
  "event": "<string>",
  "payload": {
    "installment_uuid": "<string>",
    "repayment_schedule": {
      "repayment_schedule_uuid": "<string>",
      "is_active": "<boolean>"
    },
    "fixed_amount": "<decimal as string>",
    "due_date": "<ISO8601 date as string or null>",
    "installment_number": "<integer>",
    "status": "<string>",
    "last_payment_date": "<ISO8601 date as string or null>",
    "present_value": "<decimal as string>",
    "total_paid_in_progress": "<decimal as string>",
    "total_paid": "<decimal as string>",
    "is_fully_paid": "<boolean>",
    "pending_amount": "<decimal as string>"
  }
}

Example Payload:

{
  "created_at": "2025-01-03T10:10:00Z",
  "event": "installment_status_changed",
  "payload": {
    "installment_uuid": "789e0123-e89b-12d3-a456-426614174222",
    "repayment_schedule": {
      "repayment_schedule_uuid": "456e7890-e89b-12d3-a456-426614174111",
      "is_active": true
    },
    "fixed_amount": "1200.00",
    "due_date": "2025-01-15",
    "installment_number": 3,
    "status": "partially_paid",
    "last_payment_date": "2025-01-02",
    "present_value": "1000.00",
    "total_paid_in_progress": "200.00",
    "total_paid": "800.00",
    "is_fully_paid": false,
    "pending_amount": "400.00"
  }
}

The possible statuses are: paid, partially_paid and not_paid.