Record a manual payment
Record a manual payment. Records money received outside Hoursmith (bank transfer, cash, cheque) against a SENT invoice; moves no money. Exactly one of `amount` or `fullBalance: true`. Overpayment, a non-SENT invoice (409), a client payment still being settled (409; a bank payment can take a few business days), a future paidDate or more decimals than the currency allows (422) are rejected. A payment can never be deleted; one that covers the balance permanently marks the invoice PAID. Optional receipt email goes only to the client's billing address; it spends the per-user, Free/trial Hoursmith-sender and per-workspace send budgets, and a spent budget never refuses the payment: it is recorded and receiptEmail reports the receipt as failed, with a warning naming the wait. Domain-idempotent: a retry with the same Idempotency-Key (or hosted requestId), even concurrent, returns the original payment (200, replayed: true) instead of recording twice. Write scope; Owner/Admin only. Available on every plan with API access.
Authorization
BearerAuth Personal Access Token. Mint at Settings → API. Token shape: hsk_<env>_<prefix12>_<secret32>.
In: header
Path Parameters
Invoice id.
Header Parameters
Caller-generated UUID/ULID. Same key + same body within 24h replays the original response; money writes are additionally idempotent at the domain level for that key.
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/invoices/497f6eca-6276-4993-bfeb-53cbbbba6f08/payments" \ -H "Idempotency-Key: string" \ -H "Content-Type: application/json" \ -d '{}'{ "data": { "payment": { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "invoiceId": "4f163819-178d-470c-a246-d6768476a6ec", "kind": "payment", "provider": "manual", "status": "pending", "amount": "string", "feeAmount": "string", "feeLabel": "string", "currency": "string", "paidDate": "2019-08-24", "methodId": "a79e32ca-882c-452b-a096-350276aed28d", "methodLabel": "string", "note": "string", "refundOfPaymentId": "60024239-4a50-4f20-bd85-d743a04f16d0", "refunded": { "amount": "string", "feeAmount": "string" }, "refundable": { "amount": "string", "feeAmount": "string" }, "refundPending": true, "refundableViaApi": true, "createdAt": "2019-08-24T14:15:22Z" }, "invoice": { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "number": "string", "clientId": "5e505642-9024-474d-9434-e5a44f505cc5", "status": "DRAFT", "paymentStatus": "unpaid", "currency": "string", "total": "string", "amountPaid": "string", "balanceDue": "string", "issueDate": "2019-08-24", "dueDate": "2019-08-24", "sentAt": "2019-08-24T14:15:22Z", "lastSentAt": "2019-08-24T14:15:22Z", "paidAt": "2019-08-24T14:15:22Z" }, "receiptEmail": { "status": "sent", "error": "string" }, "replayed": true }, "warnings": [ "string" ]}{ "data": { "payment": { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "invoiceId": "4f163819-178d-470c-a246-d6768476a6ec", "kind": "payment", "provider": "manual", "status": "pending", "amount": "string", "feeAmount": "string", "feeLabel": "string", "currency": "string", "paidDate": "2019-08-24", "methodId": "a79e32ca-882c-452b-a096-350276aed28d", "methodLabel": "string", "note": "string", "refundOfPaymentId": "60024239-4a50-4f20-bd85-d743a04f16d0", "refunded": { "amount": "string", "feeAmount": "string" }, "refundable": { "amount": "string", "feeAmount": "string" }, "refundPending": true, "refundableViaApi": true, "createdAt": "2019-08-24T14:15:22Z" }, "invoice": { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "number": "string", "clientId": "5e505642-9024-474d-9434-e5a44f505cc5", "status": "DRAFT", "paymentStatus": "unpaid", "currency": "string", "total": "string", "amountPaid": "string", "balanceDue": "string", "issueDate": "2019-08-24", "dueDate": "2019-08-24", "sentAt": "2019-08-24T14:15:22Z", "lastSentAt": "2019-08-24T14:15:22Z", "paidAt": "2019-08-24T14:15:22Z" }, "receiptEmail": { "status": "sent", "error": "string" }, "replayed": true }, "warnings": [ "string" ]}{ "error": { "code": "unauthenticated", "message": "string", "fields": { "property1": "string", "property2": "string" }, "requiredPlan": "studio", "feature": "string", "requestId": "string" }}{ "error": { "code": "unauthenticated", "message": "string", "fields": { "property1": "string", "property2": "string" }, "requiredPlan": "studio", "feature": "string", "requestId": "string" }}{ "error": { "code": "unauthenticated", "message": "string", "fields": { "property1": "string", "property2": "string" }, "requiredPlan": "studio", "feature": "string", "requestId": "string" }}{ "error": { "code": "unauthenticated", "message": "string", "fields": { "property1": "string", "property2": "string" }, "requiredPlan": "studio", "feature": "string", "requestId": "string" }}{ "error": { "code": "unauthenticated", "message": "string", "fields": { "property1": "string", "property2": "string" }, "requiredPlan": "studio", "feature": "string", "requestId": "string" }}{ "error": { "code": "unauthenticated", "message": "string", "fields": { "property1": "string", "property2": "string" }, "requiredPlan": "studio", "feature": "string", "requestId": "string" }}List an invoice's payments and refunds
Read-only ledger, oldest first: payments and refunds with exact decimal amounts, fees, paidDate (YYYY-MM-DD), method label, the operator's note (refund rows carry none), refundOfPaymentId, and per succeeded payment the refunded and refundable totals. Provider account references and provider payment ids are never returned. Read scope; Owner/Admin/Manager (Members get 403).
Record a manual refund
Records money from a MANUAL payment that was already returned outside Hoursmith; moves no money. Card (Stripe) payments are rejected with 409 — issue those refunds in the Hoursmith app. Exactly one of `amount` or `fullRemaining: true` (remaining principal and fee). Refunds cannot be deleted and never reopen a PAID invoice. Domain-idempotent per Idempotency-Key/requestId. Write scope; Owner/Admin only.