Disbursement Payload

What It Does

Use category: "disbursement" for financed money. Set data.kind to choose shape:

loan: money disbursed directly to one client.
purchase: goods or purchase financing allocated to one or more clients.

Send downstream payment payloads with the same disbursement_id. Add operation payloads only when you need to track the underlying operation or asset.

Field Summary

Required Fields

Field	Required	Notes
`disbursement_id`	Always	Unique disbursement identifier.
`step`	Always	`create`, `update`, or `delete`.
`kind`	Create	`loan` or `purchase`.
`disbursement_amount`	Create	Financed amount.
`total_expected_margin`	Create	Total expected margin.
`currency`	Create	ISO 4217 code, for example `USD`.
`client_id`	Loan create	Borrower client id. Do not send on purchases.
`disbursement_date`, `maturity_date`	Loan create	ISO 8601 date input, either date-only or timestamp.
`operation_date`	Purchase create	Purchase operation date. Accepts ISO 8601 date-only or timestamp input.
`payment_date`	Purchase create	Purchase operation payment date. Accepts ISO 8601 date-only or timestamp input.
`estimated_delivery_date`	Purchase create	Estimated goods payments delivery date. Accepts ISO 8601 date-only or timestamp input.
`goods_description`	Purchase create	Description of the financed goods.
`goods_status`	Purchase create	Status of the financed goods.

Required Field when updating:

Required when an update changes maturity date, expected margin, or amount.

Field	Required	Notes
`change_date`	Required	Date on which the change occured
`change_reason`	Required	Reason for the change to occur.

Common optional fields:

Field	Notes
`purchase_clients`	Client links for purchase disbursements. Each item only needs `client_id`; purchase id comes from `disbursement_id`.
`gross_value`	Total gross value of the disbursement before taking the upfront fee.
`upfront_fee`	Additional fee taken at origination: `gross_value` - `disbursement_amount`.
`installment_count`	Number of installments expected for the disbursement.
`decision_date`	Date of the credit or financing decision. Accepts ISO 8601 date-only or timestamp input.
`decision`	Credit or financing decision outcome.
`credit_score`	Credit score used for the decision, when available.
`reason`	Reason or explanation for the decision.
`approved_amount`	Amount approved during the decision process.
`pledge_creditor`	Creditor assigned to the disbursement when another creditor holds the pledge.
`bank_ref`	Bank or processor reference for the disbursement.
`insurer_coverage`	Insurance coverage value for the disbursement, when insured.
`insurer_name`	Name of the insurer, when insured.
`info`	Additional structured metadata.

If the disbursement is assigned to another creditor, declare that creditor in pledge_creditor.

Create Loan

{
  "category": "disbursement",
  "data": {
    "step": "create",
    "disbursement_id": "DSB-2024-001",
    "kind": "loan",
    "client_id": "BR-2024-001",
    "disbursement_amount": 10000,
    "currency": "USD",
    "total_expected_margin": 1293,
    "disbursement_date": "2024-10-20T12:34:56Z",
    "maturity_date": "2025-10-20T12:34:56Z",
    "upfront_fee": 200,
    "gross_value": 10200
  }
}

Create Purchase

{
  "category": "disbursement",
  "data": {
    "step": "create",
    "disbursement_id": "DSB-2024-002",
    "kind": "purchase",
    "purchase_clients": [
      {
        "client_id": "BR-2024-001"
      }
    ],
    "disbursement_amount": 15000,
    "currency": "USD",
    "total_expected_margin": 2000,
    "operation_date": "2024-10-20T12:34:56Z",
    "payment_date": "2024-10-20T12:34:56Z",
    "estimated_delivery_date": "2025-10-20T12:34:56Z",
    "goods_description": "Agricultural Equipment - Tractor",
    "goods_status": "delivered"
  }
}

Update

Use step: "update" with the same disbursement_id and fields to change.

{
  "category": "disbursement",
  "data": {
    "step": "update",
    "disbursement_id": "DSB-2024-001",
    "maturity_date": "2025-12-20T12:34:56Z",
    "change_date": "2024-12-20T12:34:56Z",
    "change_reason": "Client requested revised maturity date"
  }
}

Delete

Use step: "delete" with only the id.

{
  "category": "disbursement",
  "data": {
    "step": "delete",
    "disbursement_id": "DSB-2024-001"
  }
}

Notes

Old top-level loan and purchase categories are replaced by disbursement.kind.
Use client_id for loans.
Do not use client_ids, it is no longer supported.
Do not send purchase_clients for loans or client_id for purchases.
Use purchase_clients on purchases to link clients to a purchase.
Each purchase_clients item contains only client_id; the purchase id is the parent disbursement_id.
All _date fields accept ISO 8601 date input, either date-only or timestamp.
Creating a disbursement also creates an ongoing disbursement status.
Updating maturity_date, reducing total_expected_margin, or reducing disbursement_amount creates history rows. Include change_date and change_reason for those updates.
Keep currency consistent across related disbursement, payment, and operation payloads.