Rent and payments

Charges are what a tenant owes. Payments are money received. Allocations connect the two, and a payment is not applied to a balance until it is allocated.

charge ──┐
charge ──┼── allocation ──> payment
charge ──┘

A payment can be split across several charges, and a charge can be settled by several payments.

Creating a charge

Recurring rent is generated from the lease’s rentChargeDay, so you only create charges by hand for one-offs:

curl -X POST https://api.getvespy.com/api/charges \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "leaseId": "'"$LEASE_ID"'",
    "tenantId": "'"$TENANT_ID"'",
    "categoryId": "'"$CATEGORY_ID"'",
    "chargeType": "fee",
    "name": "Late fee — September",
    "amountCents": 7500,
    "dueDate": "2026-09-06"
  }'

chargeType is one of rent, fee, deposit, adjustment, or other. categoryId points at the chart of accounts and determines how the charge lands in the ledger — list the options with GET /api/categories. Categories are system-managed; PATCH and DELETE on one return 405.

To make a charge repeat without going through the lease, pass recurrence with a frequency, dayOfMonth, and startDate.

Recording a payment

curl -X POST https://api.getvespy.com/api/payments \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "tenantId": "'"$TENANT_ID"'",
    "leaseId": "'"$LEASE_ID"'",
    "amountCents": 192500,
    "paymentMethod": "check",
    "checkNumber": "1041",
    "receivedAt": "2026-09-06T15:04:00Z",
    "idempotencyKey": "a3f1e0c2-8b5d-4a71-9e33-2c6d0f5b7a19",
    "allocations": [
      { "chargeId": "'"$RENT_CHARGE_ID"'", "amountCents": 185000 },
      { "chargeId": "'"$LATE_FEE_CHARGE_ID"'", "amountCents": 7500 }
    ]
  }'

paymentMethod is ach, card, cash, check, or other.

Caution

idempotencyKey is required, not optional. Generate one UUID per real-world payment and reuse it if you retry — a repeat with the same key returns the original payment instead of double-recording the money.

Allocations are optional at creation. Omit them to record money now and apply it later with POST /api/payments/{id}/allocate. Allocation totals may not exceed the payment amount; exceeding it fails with 400 and an errors entry on allocations.

Corrections

The rules here are deliberately narrow, because payments feed the trust ledger.

To do this	Use
Fix how a payment was split	PUT or DELETE on /api/payments/{id}/allocations/{allocationId}
Mark a check as bounced	POST /api/payments/{id}/transition with {"status":"failed"}
Undo a payment entirely	POST /api/payments/{id}/reverse
Cancel a charge that should not have been billed	POST /api/charges/{id}/void

PUT /api/payments/{id} always returns 409. Payments are immutable once recorded — reverse and recreate rather than edit. This is what keeps the ledger auditable.

Checking a balance

curl "https://api.getvespy.com/api/tenants/$TENANT_ID/ledger" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

The tenant ledger is the authoritative view of what is owed: charges, payments, and the running balance in one ordered list.

Taking payment online

Everything above records money you collected yourself. To have tenants pay through the platform, see the Online Payments endpoints — Stripe Connect onboarding, saved payment methods, and autopay. Those flows create the payment records for you.