https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=42785 Bug ID: 42785 Summary: REST API: Add atomic external payment intake endpoint for patron-linked charges from third-party systems Initiative type: --- Sponsorship --- status: Product: Koha Version: Main Hardware: All OS: All Status: NEW Severity: enhancement Priority: P5 - low Component: REST API Assignee: koha-bugs@lists.koha-community.org Reporter: martin.renvoize@openfifth.co.uk QA Contact: testopia@bugs.koha-community.org CC: tomascohen@gmail.com When an external system (self-service kiosk, third-party POS terminal, payment gateway) needs to record a completed patron payment in Koha, it currently requires two sequential API calls: 1. POST /patrons/{patron_id}/account/debits â create the charge 2. POST /patrons/{patron_id}/account/credits â record the payment against it This two-step flow has practical problems for external integrations: - It is not atomic: a failure between the two calls leaves an unpaid debit on the patron's account - External systems typically have a single "payment completed" event to record, not separate "charge" and "pay" steps - The correct debit to credit linkage (via account_offsets) must be managed by the caller A new endpoint oriented at external payment intake would allow this in a single call: POST /patrons/{patron_id}/account/payments ...accepting a debit_type, amount, description, payment_type, and optionally a register_id (to journal against a POS cash register), and atomically creating the debit, the credit, and the offset linking them. This mirrors what happens internally in the SIP2 FeePayment path (which creates a charge-and-pay in one transaction) and makes the REST API a first-class integration surface for external payment systems such as Bibliotheca kiosks with Netloan, self-checkout terminals, and payment gateways. Use case: A Bibliotheca kiosk authenticates a patron via SIP2 and takes payment for a booking or printing job. The kiosk should be able to POST a single "payment received" record to Koha â creating the income line and immediately marking it as paid, journaled to the correct cash register â without managing a two-step debit/credit dance. Test plan: 1. Identify a patron with no outstanding charges 2. POST to /api/v1/patrons/{patron_id}/account/payments with debit_type, amount, payment_type, and a valid register_id 3. Confirm a debit and a credit line are both created in accountlines, linked via account_offsets, with amountoutstanding = 0 on the debit 4. Confirm the patron's account balance is unchanged (net zero) 5. Confirm the transaction appears in the specified cash register's daily total -- You are receiving this mail because: You are the assignee for the bug. You are watching all bug changes.