File a pending supplier-payment draft (human approves in Taokeh)
create_payment_draftFILES A PENDING DRAFT ONLY — NOTHING CHANGES UNTIL A HUMAN REVIEWS AND APPROVES IT IN TAOKEH. File a SUPPLIER-PAYMENT draft ("we paid Ah Seng RM5,000 from Maybank on Tuesday against bills 12 and 14"). This does NOT post: only the owner's approval writes a real bank payment and settles the bills, and when it does, accounts payable and the bank move exactly as they would if the owner had matched the line in Banking. A payment settles an EXISTING supplier's open bills: resolve the supplier (resolve_vendor) and see what is owed (ap_aging, search_documents) first, then give EITHER a lump total (auto-allocated oldest-first) OR explicit per-bill allocations. PREFER purchaseId over reference in an allocation: a supplier's own bill number is NOT unique in Taokeh, so a reference that matches two open bills is refused naming both rather than guessed. MYR only — a foreign-currency bill is refused and routes to Banking → Match, which handles the exchange difference. Amounts are RINGGIT, the same figures ap_aging and search_documents show you — never sen, never a foreign figure converted by you. A CREDIT CARD can't be the paying account here: paying a supplier on a card is a spend that arrives on the card's own statement — import that statement instead. IF THIS COMPANY IMPORTS BANK STATEMENTS and the payment is already sitting on an imported line, do NOT file here — propose the allocation on that line with draft_bank_classification. Filing it here would put the same money in Taokeh twice, and the server refuses when it can see the imported line. The server re-derives the allocation against live outstanding at create AND at approval, so its figures are authoritative and a bill settled in the meantime makes the draft refuse rather than over-pay. A bill's outstanding is NET of the live debit notes raised against it (a RM 432 bill with a RM 363.13 debit note owes 68.87; ap_aging lists the note as its own negative row, so the supplier's total there is already net): a lump total auto-allocates into those net figures only. An explicit per-bill amount may go up to the bill's open amount BEFORE its debit notes — paying the whole bill is allowed, and the excess then stays on the debit note as the supplier's refundable credit — so propose the net figure unless the user says they paid the full bill. Set needsReview and add a SHORT reviewer note in notes (one or two sentences naming what to double-check — not lengthy reasoning) for any doubt. Filed it wrong? Use revise_draft (kind: 'payment') rather than filing a second one. If you have the payment proof (transfer slip, remittance advice), attach the original document you extracted from — the owner sees it beside the draft at review (s.82 record-keeping) and it lands on the settlement entry automatically on approval. Small files: attachmentBase64 + attachmentMediaType inline. Send attachmentBytes (the original file’s decoded size) with it so a truncated base64 is rejected instead of filed. Anything bigger: request_attachment_upload → PUT the bytes → pass the returned attachmentToken — unless your shell cannot reach taokeh.my (a sandboxed client behind a network allowlist), in which case inline it anyway, with attachmentBytes; never both.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| notes | No | A SHORT reviewer note: one or two plain sentences, written in the reviewer's language, flagging what the human should double-check before approving — a smudged or ambiguous total, a supplier you weren't sure of, a judgment call you made. The reviewer reads this on a small approval card, so keep it brief and human. This is NOT a place to dump lengthy reasoning, your working, or boilerplate — just the one thing to check. Leave it empty when there is nothing to flag. | |
| total | No | A lump ringgit amount to auto-allocate oldest-first across the supplier’s open bills. Give this OR explicit allocations — never both. | |
| vendor | No | The supplier name, resolved with resolve_vendor first. A payment settles an EXISTING supplier's bills and can never create a supplier. | |
| vendorId | No | The resolved vendor id, instead of the name. | |
| allocations | No | The explicit per-bill split, at most 50 lines. Each amount is capped by the server at that bill’s live open amount before its debit notes. | |
| needsReview | No | ||
| paymentDate | Yes | ||
| printedTotal | No | The total printed on the payment advice, if any. Cross-check only — the server computes the real total and flags a mismatch on the approval screen. | |
| bankAccountId | No | The PAYING bank/cash account (from intake_contract(doc_type:'payment') → payingAccounts). Optional — omit it and the reviewer picks at approval. A credit-card account is refused by name. | |
| attachmentBytes | No | The decoded byte size of the ORIGINAL file on disk — send it alongside attachmentBase64 and the server rejects a truncated paste instead of filing a corrupt file. | |
| attachmentToken | No | The token from request_attachment_upload, AFTER you have PUT the file bytes to its uploadUrl. Use this instead of attachmentBase64 for any real photo/PDF — it carries the file out-of-band (no base64 in this call). Mutually exclusive with attachmentBase64. The uploaded file rides the draft and lands on the settlement entry on approval, exactly as an inline one does. | |
| attachmentBase64 | No | The ORIGINAL payment proof (transfer slip / remittance advice) as base64 — SMALL files only (a few KB). For a real photo or multi-page PDF use request_attachment_upload instead (attachmentToken). Rides the draft and lands on the settlement entry on approval — no re-upload. A bad type/oversize file is rejected and NOTHING is filed. | |
| attachmentSha256 | No | The SHA-256 of the ORIGINAL file as 64 hex chars — optional second check alongside attachmentBase64, so corrupted bytes are rejected instead of filed. | |
| attachmentFilename | No | Optional original filename for the attachment, e.g. transfer-slip.jpg. | |
| attachmentMediaType | No | The attachment's MIME type, e.g. 'image/jpeg' or 'application/pdf'. Required when attachmentBase64 is given. It must match the file's bytes — a mismatch is refused and nothing is filed. |