Bills

Before the first bill

• Set your webhook address on Connect: bills answer 409 until there is one.
• Make the payer: PUT /api/org/v1/payers/:externalRef without balanceMinor. You get its payment number to print or text.

Create a bill

curl -X POST https://wellth.example/api/org/v1/bills \
  -H "Authorization: Bearer $WELLTH_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "payerRef": "pt_4471",
    "externalRef": "inv_20931",
    "description": "Clinic services",
    "amountMinor": "30000",
    "currency": "UGX",
    "dueAt": "2026-11-30T00:00:00Z"
  }'

{
  "id": "cm3x8k2p40001ab12cd34ef56",
  "externalRef": "inv_20931",
  "payerRef": "pt_4471",
  "payNumber": "4027186354",
  "description": "Clinic services",
  "amountMinor": "30000",
  "paidMinor": "0",
  "currency": "UGX",
  "siteCode": "kyanja",
  "dueAt": "2026-11-30T00:00:00.000Z",
  "status": "OPEN",
  "createdAt": "2026-11-01T09:05:42.000Z"
}

status is OPEN, PAID (paid in full) or CANCELLED. The payer's balanceMinor goes up by the bill at once.

Read or cancel a bill

Something already paid on it: 409 “Something was already paid on this bill, so it can't be cancelled.” (or the same for a family share). A share with a payment on its way: 400, wait until it lands or fails. For a part refund, talk to Tall Grass.

How a payment goes to bills

• A payer pays any whole amount up to the balance with their number. Wellth puts it on the open bills oldest first: by due date (bills without one last), then by when they were made.
• You get one learner.payment_succeeded for the whole payment, and one bill.payment_succeeded for each bill it touched, with that bill's part and whether the bill is now PAID.
• Staff can split a bill into family shares in the portal (“Sister, London”): each share is a collection with its own link and pay code, and its payment comes as collection.payment_succeeded plus bill.payment_succeeded.

Descriptions, by type of organisation

A bill's description, and the termLabel any organisation but a school sends on payers and collections, is one of these. A school's termLabel can be any text up to 40 characters.