Skip to main content
Payments represent individual payment records against a tradeline. Each payment automatically updates the tradeline’s status, balance, and 24-month payment history.

​
Reporting a payment

curl -X POST https://vvdufluovypptsnkihyv.supabase.co/functions/v1/payments \
  -H "x-api-key: sk_test_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "tradeline_id": "9c843590-8552-4490-a50c-f0cc413d8b69",
    "payment_date": "2026-02-01",
    "period_start": "2026-02-01",
    "period_end": "2026-02-28",
    "amount_due": 150000,
    "amount_paid": 150000,
    "payment_status": "on_time"
  }'

​
Request fields

FieldTypeRequiredDescription
tradeline_iduuidYesThe tradeline this payment is for
payment_datestringYesYYYY-MM-DD — when the payment was made
period_startstringNoBilling period start (YYYY-MM-DD)
period_endstringNoBilling period end (YYYY-MM-DD)
amount_dueintegerYesAmount due this period in cents
amount_paidintegerYesAmount actually paid in cents
payment_statusenumYesSee payment_status enum
external_payment_idstringNoYour internal transaction ID. Max 255 chars.

​
Response

The response includes the payment record plus a tradeline_status snapshot: 
{
  "id": "1bedd1b0-aadd-4d0e-8d23-68b2f9d30efb",
  "tradeline_id": "9c843590-8552-4490-a50c-f0cc413d8b69",
  "payment_date": "2026-02-01",
  "amount_due": 150000,
  "amount_paid": 150000,
  "payment_status": "on_time",
  "reported": false,
  "tradeline_status": {
    "account_status": "current",
    "current_balance": 0,
    "amount_past_due": 0,
    "payment_history": "0"
  }
}

​
Auto-updates on tradeline

When you report a payment, the API automatically:
  1. Updates account_status based on payment_status
  2. Recalculates current_balance from amount_due - amount_paid
  3. Updates amount_past_due (non-zero when delinquent)
  4. Appends to payment_history (24-month rolling string)
  5. Tracks highest_balance if current balance exceeds previous high
  6. Sets date_of_first_delinquency on first non-current payment

​
Duplicate prevention

Each (tradeline_id, period_start) combination must be unique. Submitting a duplicate returns 409 CONFLICT.

​
Listing payments

Payments are listed per-tradeline. The tradeline_id query parameter is required. 
curl "https://vvdufluovypptsnkihyv.supabase.co/functions/v1/payments?tradeline_id=9c843590-8552-4490-a50c-f0cc413d8b69" \
  -H "x-api-key: sk_test_your_api_key_here"
Payments are ordered by payment_date descending.