Payment Terms Structure - When & How Money Moves

Core Concept

A payment_term describes the timing and method for paying out a single financial obligation (from any clause type—financial, benefit, etc.). It answers:

• When is the money due?
• How is it paid (ACH, check, wire, etc.)?
• What's the payment structure (lump sum, installments, recurring)?

The payment_term does NOT answer "why is this money owed?" That's the clause's job.

---

Payment_Terms Array Structure

Each financial_clause can have one or more payment_terms entries. The amount must sum up to the amount of the financial_clause (if the clause amount is fixed) or be defined logically to cover the total obligation.

{
  "financial_clause_id": "clause_guarantee_vs_nbor",
  "name": "Guarantee vs NBOR",
  "amount": 25000,
  
  "payment_terms": [
    {
      "payment_term_id": "pt_advance_001",
      "payment_term_name": "50% Advance",
      "status": "scheduled",
      "amount": { "type": "percentage", "value": 50 },
      "due_date": { "type": "absolute", "value": "2025-11-15" }
    },
    {
      "payment_term_id": "pt_balance_001",
      "payment_term_name": "Balance",
      "status": "pending",
      "amount": { "type": "percentage", "value": 50 },
      "due_date": { "type": "relative", "offset_days": 0, "trigger": "SHOW_SETTLED.status == 'C'" }
    }
  ]
}

---

Payment_Terms Schema Definition

1. Payment Term Object

Field	Type	Description
payment_term_id	string	Unique identifier (e.g., pt_adv_001)
payment_term_name	string	Human-readable name
status	string	Current state: pending, scheduled, ready_to_pay, paid, cancelled
payment_type	string	lump_sum, installment, recurring, holdback, advance
amount	object	Definition of how much to pay (see below)
trigger	string	(Optional) Condition for this term to become active
due_date	object	Definition of when payment is due (see below)
payment_method	string	ach, check, wire, cash, other
payment_destination_input_ref	string	Loose reference to an external ID or Input key defining where money goes (e.g., PAYMENT_PROFILE_INPUT)
special_conditions	object	Arbitrary key-value pairs for tax, FX, etc.

2. Amount Object

// Fixed Amount
{
  "type": "fixed",
  "value": 12500
}

// Percentage of Total Clause Amount
{
  "type": "percentage",
  "value": 50  // 50%
}

// Calculated Amount
{
  "type": "calculated",
  "calculation": "clause.amount - 5000"
}

3. Due Date Object

// Absolute Date
{
  "type": "absolute",
  "value": "2025-12-15"
}

// relative
{
  "type": "relative",
  "trigger": "CONTRACT_SIGNED_STATE.value == true", 
  "value": "2025-12-15"
  "calculation": "CONTRACT_SIGNED_STATE.value.date + 30 days",
  "offset_days": 30
}

// Rule-Based (Recurring)
{
  "type": "rule_based",
  "frequency": "quarterly",          // daily, weekly, monthly, quarterly, annual
  "frequency_value": 1,              // every 1 quarter
  "start_date": "2025-12-31",
  "end_date": "2026-12-31",
  "payment_day_of_period": "last_day", // first_day, last_day, specific_day_X
  "statement_lag_days": 30           // Days to pay after period closes
}

4. Generated Schedule (for Rule-Based)

When due_date.type is rule_based, the engine generates a schedule.

"generated_schedule": [
  {
    "sequence": 1,
    "period_start": "2025-10-01",
    "period_end": "2025-12-31",
    "due_date": "2026-01-30",
    "amount_projected": 4166.66
  },
  {
    "sequence": 2,
    "period_start": "2026-01-01",
    "period_end": "2026-03-31",
    "due_date": "2026-04-30",
    "amount_projected": 4166.66
  }
]

---

Detailed JSON Example

{
  "payment_term_id": "pt_advance_001",
  "payment_term_name": "50% Advance",
  
  "payment_type": "lump_sum",
  "status": "paid",
  
  "amount": {
    "type": "fixed",
    "value": 12500
  },
  
  "trigger": "CONTRACT_SIGNED.value == true",
  
  "due_date": {
    "type": "absolute",
    "value": "2025-10-01"
  },
  
  "payment_method": "wire",
  "payment_destination_input_ref": "BANK_ACCOUNT_REF",
  
  "special_conditions": {
    "currency": "USD",
    "tax_withholding": 0
  },
  
  "metadata": {
    "notes": "Paid upon signature"
  }
}