billing: document paying an invoice + withholding tax

content/api/conventions.md

@@ -143,9 +143,10 @@ The big picture. Each row is a fully-qualified API function.
 | `billing.list` / `.get` / `.create` / `.update` / `.delete` | Billing account CRUD. The account `type` (`individual`/`company`) drives the Head Office line on tax documents |
 | `billing.project` | Set the billing account on a project |
 | `billing.report` | Usage rolled up over a date range |
-| `billing.listInvoices` / `.getInvoice` / `.downloadInvoice` | Invoices. An invoice carries `taxEntityType` (buyer entity, snapshotted) and, once paid, a `receiptNumber` (`DPLY-RC-YYYYMM-NNNN`) separate from `number` |
-| `billing.downloadReceipt` | Download the receipt / tax-invoice PDF of a **paid** invoice |
-| `billing.uploadTransferSlip` | Submit a bank-transfer receipt |
+| `billing.listInvoices` / `.getInvoice` / `.downloadInvoice` | Invoices. An invoice carries `taxEntityType` (buyer entity, snapshotted) and, once paid, a `receiptNumber` (`DPLY-RC-YYYYMM-NNNN`) separate from `number`, plus `withholdingTaxRate`/`withholdingTaxAmount` when a company buyer withheld tax |
+| `billing.downloadReceipt` | Download the receipt / tax-invoice PDF of a **paid** invoice; shows any withholding-tax deduction |
+| `billing.uploadTransferSlip` | Submit a bank-transfer slip (multipart). A company buyer may set `withholdingTax` to declare a 3% deduction and attach the withholding-tax certificate (`whtCert`) |
+| `billing.uploadWHTCertificate` | Attach a withholding-tax certificate (`whtCert`, multipart) to an invoice **later** — company invoices only, allowed even after the invoice is paid |
 
 ### GitHub
 

content/billing/overview.md

@@ -94,6 +94,37 @@ curl https://api.deploys.app/billing.downloadReceipt \
   -d '{ "id": "inv_…" }'        # paid invoices only; returns the receipt PDF
 ```
 
+## Paying an invoice
+
+Invoices are settled by bank transfer. On the **Billing → Invoices** page, open
+an `open` invoice and press **Pay**: the dialog shows the seller's bank account
+and a PromptPay QR (for THB invoices) for the amount due. Transfer the amount,
+then upload your **bank transfer slip** as proof. An operator verifies the slip
+against the payment and marks the invoice **paid** — at which point it is
+assigned its receipt number and its receipt / tax-invoice PDF becomes available.
+
+### Withholding tax (หัก ณ ที่จ่าย)
+
+If your billing account is a **company** (a juristic person), you can withhold
+**3% tax** on the payment, as Thai law requires for service payments. In the
+**Pay** dialog, tick **Withhold 3% tax**:
+
+- The withheld amount is **3% of the pre-VAT subtotal** (the service value,
+  before VAT) — not of the gross total.
+- Transfer the **net** amount the dialog shows: `Total − withholding`. For
+  example, a ฿1,070 invoice (฿1,000 subtotal + 7% VAT) withholds ฿30, so you
+  transfer ฿1,040.
+- Optionally attach your **withholding tax certificate** (หนังสือรับรองการหักภาษี
+  ณ ที่จ่าย, "50 ทวิ") alongside the slip — or **later**, from the invoice page's
+  **Attach WHT certificate** button (certificates commonly arrive a few days
+  after the transfer).
+
+The invoice is still **settled in full** — the withheld 3% is remitted to the
+Revenue Department on the seller's behalf, so it is a tax credit, not an unpaid
+balance. The **receipt** shows the deduction explicitly (`Less withholding tax
+(3%)`) and the net amount received. Withholding is a company-only option;
+individual accounts pay the full total.
+
 ## Where to watch your costs
 
 Two places: