Payments

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

Field	Type	Required	Description
`tradeline_id`	uuid	Yes	The tradeline this payment is for
`payment_date`	string	Yes	YYYY-MM-DD — when the payment was made
`period_start`	string	No	Billing period start (YYYY-MM-DD)
`period_end`	string	No	Billing period end (YYYY-MM-DD)
`amount_due`	integer	Yes	Amount due this period in cents
`amount_paid`	integer	Yes	Amount actually paid in cents
`payment_status`	enum	Yes	See payment_status enum
`external_payment_id`	string	No	Your 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:

Updates account_status based on payment_status
Recalculates current_balance from amount_due - amount_paid
Updates amount_past_due (non-zero when delinquent)
Appends to payment_history (24-month rolling string)
Tracks highest_balance if current balance exceeds previous high
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.

Getting Started

Core Concepts

Reference

Migration

Reporting a payment

Request fields

Response

Auto-updates on tradeline

Duplicate prevention

Listing payments

​Reporting a payment

​Request fields

​Response

​Auto-updates on tradeline

​Duplicate prevention

​Listing payments

Reporting a payment

Request fields

Response

Auto-updates on tradeline

Duplicate prevention

Listing payments