> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://api-docs.papertracc.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://api-docs.papertracc.com/_mcp/server.

# Overview

Payment and payable endpoints mounted at `/payments`.

## Withholding tax on payments

An allocation can withhold tax from the vendor by carrying a withholding tax profile (a tax profile with `kind` of `WHT`).

| Field        | Description                                                                                                                                     |
| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `wht_tax_id` | The withholding tax profile to apply to the allocation.                                                                                         |
| `wht_base`   | The amount the rate applies to. Optional, and cannot exceed the allocation `amount`. When omitted it follows the profile's `withholding_basis`. |

The allocation `amount` is still the gross amount settled against the bill, so the bill is cleared at its full value. The tax withheld is the rate applied to the base, rounded to two decimal places. It is credited to the profile's withholding tax payable account, and the cash leaving the payment account is the gross amount less the total withheld.

Without a `wht_base`, the base comes from the profile's `withholding_basis`:

| Basis                | Base used                                                                          |
| -------------------- | ---------------------------------------------------------------------------------- |
| `EXCL_VAT` (default) | The allocation `amount` less the share of it that is VAT on the bill's line items. |
| `INCL_VAT`           | The allocation `amount`.                                                           |

For example, take a 1,075.00 bill made up of 1,000.00 plus 75.00 VAT, paid in full with a 5% profile and no `wht_base`. With `EXCL_VAT` the base is 1,000.00, so 50.00 is withheld and 1,025.00 is paid out. With `INCL_VAT` the base is 1,075.00, so 53.75 is withheld and 1,021.25 is paid out. Either way the bill is cleared for 1,075.00.

Each allocation in a payment response reports `wht_tax_id`, `wht_rate`, `wht_base` and `wht_amount`. Allocations without withholding return a null `wht_tax_id` and `0.00` for the others.

Voiding a payment reverses the withholding along with the rest of the entry.

## Early-payment discounts

A bill on a payment term with a discount can be settled for less than its balance while the discount window is open. The window and the amount are on the bill as `payment_schedule.discount`, with `deadline` and `amount`.

To take the discount, allocate the bill's balance less the discount, with a `payment_date` on or before the deadline. More precisely, an allocation that falls short of the balance by no more than the discount settles the bill in full, and the shortfall is recorded as the discount.

| Field                      | Description                                                                            |
| -------------------------- | -------------------------------------------------------------------------------------- |
| `amount` on the allocation | Returned as the full amount settled against the bill, the cash paid plus the discount. |
| `discount_amount`          | The discount taken. `0.00` when none was taken.                                        |

For example, take a 100,000.00 bill with a 2% discount open until 28 June. Allocating 98,000.00 on 25 June clears the bill: the allocation comes back with an `amount` of 100,000.00 and a `discount_amount` of 2,000.00, 98,000.00 leaves the payment account and 2,000.00 is credited to Other Income.

An allocation dated after the deadline, or one that falls short by more than the discount, is an ordinary part payment and leaves the remainder outstanding. Withholding tax on the allocation is worked out before the discount is added.