Payment Event FAQ

Overview

Payment events record transactions against a disbursement. Payment covers both received payments and scheduled / expected payments, so a repayment schedule is represented as a series of expected payments (one per installment) rather than a separate schedule category.

Required Fields

payment_id (string)

Question: What is the payment_id?

Answer: A unique identifier for this payment transaction. Used for idempotency and for updating the payment later (e.g., an expected payment becoming paid).

Example: "PAY-2024-001"

disbursement_id (string)

Question: What disbursement does this payment apply to?

Answer: The parent disbursement id. The backend requires this field and checks that the disbursement exists.

Example: "DSB-2024-001"

step (string, enum)

Question: What are the valid values for step?

Answer:

• create: Create a new payment record
• update: Update existing payment information (e.g., flip status from expected to paid)
• delete: Delete a payment record by payment_id

payment_total (number)

Question: What is the total payment amount?

Answer: Total amount of the payment (expected or received). Positive number.

Example: 500

currency (string)

Question: What currency is the payment in?

Answer: ISO 4217 currency code. Must match the disbursement's currency.

Example: "USD"

status (string, enum)

Question: What values are allowed for status?

Answer:

• expected — a planned / scheduled payment that has not yet been received. Use this to model a repayment schedule.
• paid — a payment that has been received.
• canceled — a payment that was planned but is no longer expected.

Example: "paid"

source (string, enum)

Question: Who made or funded the payment?

Answer:

• client — payment came from the client.
• insurer — payment came from an insurer.
• other — payment came from another source.

Example: "client"

due_date (date) — new in 3.6.1

Question: When is the payment due?

Answer: Required due date for the payment or installment. Use date-only YYYY-MM-DD format.

Example: "2024-11-20"

Optional Fields

payment_date (date-time)

Question: When was the payment received?

Answer: Optional actual date the payment was received. Use it mainly when status = paid. ISO 8601 format.

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

payment_principal (number)

Question: What is the principal portion?

Answer: The portion of payment_total applied against the principal balance. If omitted, it is computed from the disbursement's terms.

Example: 400

payment_fee (number) — new in 3.5.0

Question: What is payment_fee?

Answer: The interest / fee portion of the payment. By construction payment_fee = payment_total - payment_principal (i.e. anything paid above principal is the interest/fee). If omitted, it is inferred from payment_total - payment_principal.

Example: 100

installment_number (number) — new in 3.5.0

Question: What is installment_number?

Answer: The installment index this payment corresponds to. Starts at 1 for the first scheduled repayment (2, 3, … for subsequent ones). 0 is reserved for the upfront fee, which is captured directly on the disbursement via upfront_fee and must not be sent as a payment event. Strongly recommended when status = expected so a received payment can be linked back to its scheduled slot.

Example: 1

bank_ref (string)

Question: Can I store a bank reference?

Answer: Optional reference number / identifier from the bank for this payment.

Example: "BANK-REF-12345"

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: How do I model a repayment schedule now that the schedule category is removed?

A: Send one payment event per installment with status: "expected", a unique payment_id, a required due_date, and an installment_number.

Example (3 installments):

{ "payment_id": "PAY-2024-E1", "status": "expected", "installment_number": 1, "due_date": "2024-11-20", ... }
{ "payment_id": "PAY-2024-E2", "status": "expected", "installment_number": 2, "due_date": "2024-12-20", ... }
{ "payment_id": "PAY-2024-E3", "status": "expected", "installment_number": 3, "due_date": "2025-01-20", ... }

Q: What value should installment_number start at?

A: Start at 1 for the first scheduled repayment. installment_number: 0 is reserved for the upfront fee charged at origination, which you should not send as a payment event — it is already captured on the disbursement itself via the upfront_fee field. So your schedule is 1, 2, 3, … for the actual repayments.

Q: How do I mark a scheduled payment as received?

A: Send an update event with the same payment_id and status: "paid". Keep installment_number so the received payment stays linked to its scheduled slot. You can also correct payment_total, payment_principal, or payment_fee in the same update.

Q: How do I cancel a scheduled installment?

A: Send an update event with the existing payment_id and status: "canceled".

Q: When should I use delete instead of status: "canceled"?

A: Use delete to remove an erroneous payment record. Use status: "canceled" when a planned installment should remain in history but no longer be expected.

Q: How is interest calculated?

A: Interest equals payment_total - payment_principal, which is the same as payment_fee. In other words payment_fee is the interest portion of the payment. If payment_principal is not specified, the system calculates it from the disbursement's terms.

Q: What happens if payment_total exceeds the remaining balance?

A: The overage is credited to margin (interest/fees) once principal is fully paid.

Q: Can I make partial payments against a single installment?

A: Yes — send multiple paid payment events with distinct payment_ids, each carrying the same installment_number.

Q: What if a payment bounces?

A: If the payment record was created in error, send step: "delete" for that payment_id. If it should remain auditable, update it to status: "canceled".

Field Dependencies

• currency must match the disbursement's currency
• disbursement_id must reference an existing disbursement
• status is required — must be expected, paid, or canceled
• source is required — must be client, insurer, or other
• due_date is required and must use YYYY-MM-DD format
• payment_total = payment_principal + payment_fee, where payment_fee is the interest portion (i.e. interest = payment_total - payment_principal = payment_fee)
• payment_date represents the actual receipt date when payment is received

Payment Flow

1. (Optional) Create the repayment schedule by inserting one expected payment per installment.

2. When a payment is received, update the matching payment_id with status: "paid" and the actual payment_total / payment_principal / payment_fee.

3. The system updates the disbursement balance accordingly.