Disbursement payload | 21yield Developers

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, reduces expected margin, or reduces disbursement amount. On partial updates, omit kind unless you also provide that kind's required linkage/date fields; the API validates the merged row.

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`	When omitted on create, defaults to the sum of individually rounded amount and upfront fee.
`upfront_fee`	Origination fee; defaults to zero. Rounded by the API before derived calculations.
`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`	Defaults to `CMK Capital` on create or when explicitly blank/non-string. Omission on update preserves the stored creditor.
`bank_ref`	Bank or processor reference for the disbursement.
`insurer_coverage`	Ratio from `0` to `1`, default `0.9`; not rounded as money.
`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.

is_pledged is deprecated and always normalized to true. Money fields are rounded by the API; extra decimals are accepted. Do not send unknown fields or content_hash.

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.
Any maturity change requires change_date and change_reason; only a later maturity generates an extension. Margin/amount reductions can generate rebate/write-off history. An unchanged content hash produces no domain effects.
Keep currency consistent across related disbursement, payment, and operation payloads.
Deletes return 409 while active dependent records exist, including applicable legacy/history dependencies. Resolve them through supported workflows; do not assume cascaded deletion or delete history blindly.
Duplicate creates return 409; missing update targets return 404. See response/retry guidance.