Receipts & payments
Money in against invoices, money out against bills — through the producer, never a status flip.
This is the "bank paid → bill marked paid" door. POST /receipts records money received from a customer against open invoices; POST /payments records money paid to a vendor against open bills. Both create a real Receipt / Payment document through the same producer the app uses — numbering, journal posting and settlement order apply — and then refresh each target's paid state. The invoice or bill becomes Paid the way it would if a person recorded it, and invoice.paid / bill.paid fire on the crossing.
curl -X POST https://api.trabalance.com/api/v1/payments \
-H "Authorization: Bearer tk_live_…" -H "Content-Type: application/json" \
-H "Idempotency-Key: BANK-OUT-20260826-0042" \
-d '{
"party_id": "<vendor id>",
"date": "2026-08-26",
"payment_account_id": "<cash-flow account id>",
"allocations": [{ "document_id": "<bill id>", "amount": 1250.00 }],
"reference": "BANK-OUT-20260826-0042"
}'| Field | Required | Notes |
|---|---|---|
| party_id | Yes | Customer id (receipts) / vendor id (payments). Every allocation must belong to this party. |
| date | Yes | YYYY-MM-DD — the date the money moved |
| payment_account_id | Yes | A cash-flow (bank/cash) account of the business — `GET /bank-feeds/accounts`. Anything else is a 400 naming the field. |
| allocations[] | Yes, ≥ 1 | `{ document_id, amount }` — the invoices / bills settled and how much of each. Unknown or foreign ids → 404; wrong type or party → 400. |
| currency, reference, note | No | reference is stored on the document and is the natural Idempotency-Key |
Response 201: { id, no, type: "Receipt" | "Payment", allocations }.
sales_receipts:create for /receipts, purchases_payments:create for /payments, finance_banking:read to list accounts. GET /receipts and GET /payments list the same documents the dashboard shows.
From a bank adapter instead
If a bank or aggregator calls you, connect a payout rail in Settings and let it call Trabalance directly with a signed payout.confirmation — see Rails.