Payment payload | 21yield Developers

What It Does

Use category: "payment" for expected installments, received payments, and canceled payments. A repayment schedule is a set of payment payloads with status: "expected".

Field Summary

Required Fields

Field	Required	Notes
`payment_id`	Always	Unique payment identifier. Reuse it when updating same payment.
`step`	Always	`create`, `update`, or `delete`.
`disbursement_id`	Create	Parent disbursement id.
`client_id`	Purchase payments	Required when the parent disbursement has `kind: "purchase"`. Loan payments resolve client from the parent loan.
`payment_total`	Create	Total expected or received amount.
`currency`	Create	ISO 4217 code. Keep aligned with disbursement.
`status`	Create	`expected`, `paid`, or `canceled`.
`due_date`	Create	ISO 8601 date input, for example `YYYY-MM-DD` or `YYYY-MM-DDTHH:mm:ssZ`.

Common optional fields:

Field	Notes
`source`	Payment source: `client`, `insurer`, or `other`. Defaults to `client`.
`payment_date`	Actual receipt timestamp, mainly for `status: "paid"`. Accepts ISO 8601 date-only or timestamp input.
`payment_principal`	Principal portion of the payment.
`payment_fee`	Fee or interest portion of the payment: `payment_total` - `payment_principal`.
`installment_number`	Installment number for schedules and repayment tracking.
`bank_ref`	Bank or processor reference for the payment.
`info`	Additional structured metadata.

Create Expected Payment

{
  "category": "payment",
  "data": {
    "step": "create",
    "payment_id": "PAY-2024-001",
    "disbursement_id": "DSB-2024-001",
    "status": "expected",
    "due_date": "2024-11-20",
    "payment_total": 500,
    "payment_principal": 400,
    "payment_fee": 100,
    "installment_number": 1,
    "currency": "USD"
  }
}

Create Paid Payment

{
  "category": "payment",
  "data": {
    "step": "create",
    "payment_id": "PAY-2024-002",
    "disbursement_id": "DSB-2024-001",
    "status": "paid",
    "source": "client",
    "due_date": "2024-11-20",
    "payment_date": "2024-11-20T12:34:56Z",
    "payment_total": 500,
    "payment_principal": 400,
    "payment_fee": 100,
    "installment_number": 1,
    "currency": "USD"
  }
}

Create Payment On Purchase

Payments on purchase disbursements must include client_id, because purchases can be linked to one or more clients.

{
  "category": "payment",
  "data": {
    "step": "create",
    "payment_id": "PAY-2024-003",
    "disbursement_id": "DSB-2024-002",
    "client_id": "BR-2024-001",
    "status": "paid",
    "due_date": "2024-11-20",
    "payment_date": "2024-11-20T12:34:56Z",
    "payment_total": 500,
    "currency": "USD"
  }
}

Update Expected To Paid

Use same payment_id and switch status.

{
  "category": "payment",
  "data": {
    "step": "update",
    "payment_id": "PAY-2024-001",
    "status": "paid",
    "payment_date": "2024-11-20T12:34:56Z",
    "payment_total": 500
  }
}

Delete

{
  "category": "payment",
  "data": {
    "step": "delete",
    "payment_id": "PAY-2024-001"
  }
}

Notes

Old top-level schedule category is replaced by one payment event per expected installment.
installment_number should start at 1 for first repayment. 0 is the upfront_fee in disbursement object.
Use status: "canceled" when planned payment should remain in history but is no longer expected.
Use step: "delete" to remove an erroneous payment.
source is optional on create; the API defaults missing source to client.
For loan disbursements, payment client_id is resolved from the parent loan.
For purchases, client_id must be linked in that disbursement's purchase_clients; an existing unrelated client is insufficient and returns 400.
All _date fields accept ISO 8601 date input, either date-only or timestamp.
Legacy entity_type and entity_id fields are tolerated but deprecated by current processing.
payment_fee represents interest/fee portion: payment_total - payment_principal.
Monetary values are rounded by the API, including extra-decimal inputs. Do not send numeric strings, unknown fields, or content_hash.
Duplicate creates return 409; missing updates return 404. A hash-matching update returns 200 unchanged, not a duplicate response; changed updates return 201.
Preserve original content and keys for retries, even when different amounts round to the same cents. See ingestion outcomes.