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: [email protected]
Reporter: [email protected]
QA Contact: [email protected]
CC: [email protected]
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.
_______________________________________________
Koha-bugs mailing list
[email protected]
https://lists.koha-community.org/cgi-bin/mailman/listinfo/koha-bugs
website : http://www.koha-community.org/
git : http://git.koha-community.org/
bugs : http://bugs.koha-community.org/
