Disbursement

Unified loan and purchase financing payloads.

Disbursement Event FAQ

Overview

Disbursement events represent the creation and management of money being disbursed to a client — either as a loan or as a purchase / goods financing. The disbursement category replaces the former loan and purchase categories introduced in earlier versions; the kind field classifies the disbursement shape.

Active downstream ingest events (operation, payment) reference the parent via required disbursement_id. The Worker creates related status/change rows such as disbursement_status, extensions, rebates, and write_offs from disbursement changes; these are not direct /ingest categories.

Required Fields

disbursement_id (string)

Question: What is the disbursement_id?

Answer: A unique identifier for the disbursement. It must be unique across all disbursements in your system.

Example: "DSB-2024-001"

kind (string, enum)

Question: What values are accepted?

Answer:

The kind drives which other fields are required (see "Kind-specific required fields" below).

Example: "loan"

step (string, enum)

Question: What are the valid values for step?

Answer:

Default: Use create for new disbursements

disbursement_amount (number)

Question: What should I set for disbursement_amount?

Answer: The financed amount. A positive number representing the principal disbursed.

Example: 10000

currency (string)

Question: What currency codes are supported?

Answer: ISO 4217 currency codes (e.g., USD, EUR, GBP).

Example: "USD"

total_expected_margin (number)

Question: What is the expected margin?

Answer: The total margin you expect to earn on this disbursement.

Example: 1293

Client linkage (client_id and/or client_ids)

Question: How do I link client(s) to a disbursement?

Answer: At least one of client_id (string) or a non-empty client_ids (array of strings) must be provided on create. The stored row keeps client_id as the primary borrower (indexed FK) plus an optional client_ids JSONB array for additional parties.

Example (single borrower):

{ "client_id": "BR-2024-001" }

Example (co-borrowers):

{ "client_id": "BR-2024-001", "client_ids": ["BR-2024-001", "BR-2024-002"] }

Kind-specific Required Fields

disbursement_date (date-time)

Question: When is disbursement_date required?

Answer: Required when kind is loan. This is when the money was disbursed to the client.

Example: "2024-10-20T12:34:56Z"

maturity_date (date-time)

Question: When is maturity_date required?

Answer: Required when kind is loan. This is when the loan is due in full.

Example: "2025-10-20T12:34:56Z"

operation_date (date-time)

Question: When is operation_date required?

Answer: Required when kind is purchase. This is when the purchase operation was initiated.

Example: "2024-10-20T12:34:56Z"

payment_date (date-time)

Question: When is payment_date required?

Answer: Required when kind is purchase. This is when payment is scheduled or made to the supplier.

Example: "2024-10-20T12:34:56Z"

estimated_delivery_date (date-time)

Question: When is estimated_delivery_date required?

Answer: Required when kind is purchase. This is when the goods are expected to be paid by the client.

Example: "2025-10-20T12:34:56Z"

goods_description (string)

Question: When is goods_description required?

Answer: Required when kind is purchase. Describe the goods being financed.

Example: "Agricultural Equipment - Tractor"

goods_status (string)

Question: When is goods_status required?

Answer: Required when kind is purchase. This is the current status of the goods (for example, pending, in_transit, or delivered).

Example: "delivered"

Optional Fields

upfront_fee (number)

Question: What is upfront_fee?

Answer: An optional upfront fee charged at disbursement. Missing or null is treated as 0.

Example: 0

gross_value (number)

Question: What is gross_value?

Answer: Optional. The gross value of the disbursement (principal plus upfront fee). If omitted or null, the processor stores gross_value = disbursement_amount + upfront_fee. If set, the provided numeric value is stored as-is.

Formula: gross_value = disbursement_amount + upfront_fee

Example: with disbursement_amount: 10000 and upfront_fee: 200, then gross_value: 10200

pledge_creditor (string)

Question: Who is the pledge creditor?

Answer: Optional identifier or name of the creditor to whom the disbursement is pledged.

bank_ref (string)

Question: Can I store a bank reference?

Answer: Optional bank-side reference for this transaction.

info (object)

Question: Can I store additional custom information?

Answer: A flexible object for custom key-value metadata.

{
  "info": {
    "key": "value",
    "customField": "customValue"
  }
}

Common Questions

Q: What happened to the loan and purchase categories?

A: They are replaced by the unified disbursement category. Use kind: "loan" or kind: "purchase" to get the equivalent behavior. Child events now use disbursement_id.

Q: How do I create a payment schedule now that schedule is removed?

A: Send a series of payment events with status: "expected" and a unique installment_number per installment. When a payment is received, update the matching payment_id with status: "paid"; to cancel an installment send status: "canceled".

Q: Can I update a disbursement after creation?

A: Yes — send an event with step: "update" and include the fields you want to change.

Q: How are extensions, rebates, and write-offs recorded now?

A: Send a disbursement update. If maturity_date changes, the Worker records an extension. If total_expected_margin decreases, it records a rebate. If disbursement_amount decreases, it records a write-off. These change rows require change_date and change_reason.

Q: What happens if I send duplicate disbursement IDs?

A: The API uses idempotency keys to detect duplicates. Same disbursement_id with same Idempotency-Key returns 200 OK with "Duplicate".

Q: Which dates are validated?

A: All *_date fields must be valid ISO 8601. For kind = loan, maturity_date should be after disbursement_date. For kind = purchase, estimated_delivery_date should be after operation_date.

Field Dependencies