3 # Copyright 2016 ByWater Solutions
5 # This file is part of Koha.
7 # Koha is free software; you can redistribute it and/or modify it
8 # under the terms of the GNU General Public License as published by
9 # the Free Software Foundation; either version 3 of the License, or
10 # (at your option) any later version.
12 # Koha is distributed in the hope that it will be useful, but
13 # WITHOUT ANY WARRANTY; without even the implied warranty of
14 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
15 # GNU General Public License for more details.
17 # You should have received a copy of the GNU General Public License
18 # along with Koha; if not, see <http://www.gnu.org/licenses>.
23 use Data::Dumper qw( Dumper );
24 use Try::Tiny qw( catch try );
26 use C4::Circulation qw( ReturnLostItem CanBookBeRenewed AddRenewal );
28 use C4::Log qw( logaction );
29 use C4::Stats qw( UpdateStats );
30 use C4::Overdues qw(GetFine);
33 use Koha::Account::Lines;
34 use Koha::Account::Offsets;
35 use Koha::Account::DebitTypes;
37 use Koha::Exceptions::Account;
41 Koha::Accounts - Module for managing payments and fees for patrons
46 my ( $class, $params ) = @_;
48 Carp::croak("No patron id passed in!") unless $params->{patron_id};
50 return bless( $params, $class );
55 This method allows payments to be made against fees/fines
57 Koha::Account->new( { patron_id => $borrowernumber } )->pay(
61 description => $description,
62 library_id => $branchcode,
63 lines => $lines, # Arrayref of Koha::Account::Line objects to pay
64 credit_type => $type, # credit_type_code code
65 item_id => $itemnumber, # pass the itemnumber if this is a credit pertianing to a specific item (i.e LOST_FOUND)
72 my ( $self, $params ) = @_;
74 my $amount = $params->{amount};
75 my $description = $params->{description};
76 my $note = $params->{note} || q{};
77 my $library_id = $params->{library_id};
78 my $lines = $params->{lines};
79 my $type = $params->{type} || 'PAYMENT';
80 my $payment_type = $params->{payment_type} || undef;
81 my $cash_register = $params->{cash_register};
82 my $item_id = $params->{item_id};
84 my $userenv = C4::Context->userenv;
86 my $manager_id = $userenv ? $userenv->{number} : undef;
87 my $interface = $params ? ( $params->{interface} || C4::Context->interface ) : C4::Context->interface;
88 my $payment = $self->payin_amount(
90 interface => $interface,
93 payment_type => $payment_type,
94 cash_register => $cash_register,
95 user_id => $manager_id,
96 library_id => $library_id,
98 description => $description,
104 # NOTE: Pay historically always applied as much credit as it could to all
105 # existing outstanding debits, whether passed specific debits or otherwise.
106 if ( $payment->amountoutstanding ) {
109 { debits => [ $self->outstanding_debits->as_list ] } );
112 my $patron = Koha::Patrons->find( $self->{patron_id} );
113 my @account_offsets = $payment->credit_offsets({ type => 'APPLY' })->as_list;
114 if ( C4::Context->preference('UseEmailReceipts') ) {
116 my $letter = C4::Letters::GetPreparedLetter(
117 module => 'circulation',
118 letter_code => uc("ACCOUNT_$type"),
119 message_transport_type => 'email',
120 lang => $patron->lang,
122 borrowers => $self->{patron_id},
123 branches => $library_id,
127 offsets => \@account_offsets,
132 C4::Letters::EnqueueLetter(
135 borrowernumber => $self->{patron_id},
136 message_transport_type => 'email',
138 ) or warn "can't enqueue letter $letter";
142 my $renew_outcomes = [];
143 for my $message ( @{$payment->object_messages} ) {
144 push @{$renew_outcomes}, $message->payload;
147 return { payment_id => $payment->id, renew_result => $renew_outcomes };
152 This method allows adding credits to a patron's account
154 my $credit_line = Koha::Account->new({ patron_id => $patron_id })->add_credit(
157 description => $description,
160 interface => $interface,
161 library_id => $library_id,
162 payment_type => $payment_type,
163 type => $credit_type,
168 $credit_type can be any of:
181 my ( $self, $params ) = @_;
183 # check for mandatory params
184 my @mandatory = ( 'interface', 'amount' );
185 for my $param (@mandatory) {
186 unless ( defined( $params->{$param} ) ) {
187 Koha::Exceptions::MissingParameter->throw(
188 error => "The $param parameter is mandatory" );
192 # amount should always be passed as a positive value
193 my $amount = $params->{amount} * -1;
194 unless ( $amount < 0 ) {
195 Koha::Exceptions::Account::AmountNotPositive->throw(
196 error => 'Debit amount passed is not positive' );
199 my $description = $params->{description} // q{};
200 my $note = $params->{note} // q{};
201 my $user_id = $params->{user_id};
202 my $interface = $params->{interface};
203 my $library_id = $params->{library_id};
204 my $cash_register = $params->{cash_register};
205 my $payment_type = $params->{payment_type};
206 my $credit_type = $params->{type} || 'PAYMENT';
207 my $item_id = $params->{item_id};
209 Koha::Exceptions::Account::RegisterRequired->throw()
210 if ( C4::Context->preference("UseCashRegisters")
211 && defined($payment_type)
212 && ( $payment_type eq 'CASH' )
213 && !defined($cash_register) );
216 my $schema = Koha::Database->new->schema;
221 # Insert the account line
222 $line = Koha::Account::Line->new(
224 borrowernumber => $self->{patron_id},
227 description => $description,
228 credit_type_code => $credit_type,
229 amountoutstanding => $amount,
230 payment_type => $payment_type,
232 manager_id => $user_id,
233 interface => $interface,
234 branchcode => $library_id,
235 register_id => $cash_register,
236 itemnumber => $item_id,
240 # Record the account offset
241 my $account_offset = Koha::Account::Offset->new(
243 credit_id => $line->id,
245 amount => $amount * -1
249 C4::Stats::UpdateStats(
251 branch => $library_id,
252 type => lc($credit_type),
254 borrowernumber => $self->{patron_id},
256 ) if grep { $credit_type eq $_ } ( 'PAYMENT', 'WRITEOFF' );
258 if ( C4::Context->preference("FinesLog") ) {
264 action => "create_$credit_type",
265 borrowernumber => $self->{patron_id},
267 description => $description,
268 amountoutstanding => $amount,
269 credit_type_code => $credit_type,
271 itemnumber => $item_id,
272 manager_id => $user_id,
273 branchcode => $library_id,
283 if ( ref($_) eq 'Koha::Exceptions::Object::FKConstraint' ) {
284 if ( $_->broken_fk eq 'credit_type_code' ) {
285 Koha::Exceptions::Account::UnrecognisedType->throw(
286 error => 'Type of credit not recognised' );
299 my $credit = $account->payin_amount(
302 type => $credit_type,
303 payment_type => $payment_type,
304 cash_register => $register_id,
305 interface => $interface,
306 library_id => $branchcode,
307 user_id => $staff_id,
308 debits => $debit_lines,
309 description => $description,
314 This method allows an amount to be paid into a patrons account and immediately applied against debts.
316 You can optionally pass a debts parameter which consists of an arrayref of Koha::Account::Line debit lines.
318 $credit_type can be any of:
326 my ( $self, $params ) = @_;
328 # check for mandatory params
329 my @mandatory = ( 'interface', 'amount', 'type' );
330 for my $param (@mandatory) {
331 unless ( defined( $params->{$param} ) ) {
332 Koha::Exceptions::MissingParameter->throw(
333 error => "The $param parameter is mandatory" );
337 # Check for mandatory register
338 Koha::Exceptions::Account::RegisterRequired->throw()
339 if ( C4::Context->preference("UseCashRegisters")
340 && defined( $params->{payment_type} )
341 && ( $params->{payment_type} eq 'CASH' )
342 && !defined($params->{cash_register}) );
344 # amount should always be passed as a positive value
345 my $amount = $params->{amount};
346 unless ( $amount > 0 ) {
347 Koha::Exceptions::Account::AmountNotPositive->throw(
348 error => 'Payin amount passed is not positive' );
352 my $schema = Koha::Database->new->schema;
357 $credit = $self->add_credit($params);
359 # Offset debts passed first
360 if ( exists( $params->{debits} ) ) {
361 $credit = $credit->apply(
363 debits => $params->{debits}
368 # Offset against remaining balance if AutoReconcile
369 if ( C4::Context->preference("AccountAutoReconcile")
370 && $credit->amountoutstanding != 0 )
372 $credit = $credit->apply(
374 debits => [ $self->outstanding_debits->as_list ]
386 This method allows adding debits to a patron's account
388 my $debit_line = Koha::Account->new({ patron_id => $patron_id })->add_debit(
391 description => $description,
394 interface => $interface,
395 library_id => $library_id,
397 transaction_type => $transaction_type,
398 cash_register => $register_id,
400 issue_id => $issue_id
404 $debit_type can be any of:
424 my ( $self, $params ) = @_;
426 # check for mandatory params
427 my @mandatory = ( 'interface', 'type', 'amount' );
428 for my $param (@mandatory) {
429 unless ( defined( $params->{$param} ) ) {
430 Koha::Exceptions::MissingParameter->throw(
431 error => "The $param parameter is mandatory" );
435 # check for cash register if using cash
436 Koha::Exceptions::Account::RegisterRequired->throw()
437 if ( C4::Context->preference("UseCashRegisters")
438 && defined( $params->{transaction_type} )
439 && ( $params->{transaction_type} eq 'CASH' )
440 && !defined( $params->{cash_register} ) );
442 # amount should always be a positive value
443 my $amount = $params->{amount};
444 unless ( $amount > 0 ) {
445 Koha::Exceptions::Account::AmountNotPositive->throw(
446 error => 'Debit amount passed is not positive' );
449 my $description = $params->{description} // q{};
450 my $note = $params->{note} // q{};
451 my $user_id = $params->{user_id};
452 my $interface = $params->{interface};
453 my $library_id = $params->{library_id};
454 my $cash_register = $params->{cash_register};
455 my $debit_type = $params->{type};
456 my $transaction_type = $params->{transaction_type};
457 my $item_id = $params->{item_id};
458 my $issue_id = $params->{issue_id};
461 my $schema = Koha::Database->new->schema;
466 # Insert the account line
467 $line = Koha::Account::Line->new(
469 borrowernumber => $self->{patron_id},
472 description => $description,
473 debit_type_code => $debit_type,
474 amountoutstanding => $amount,
475 payment_type => $transaction_type,
477 manager_id => $user_id,
478 interface => $interface,
479 itemnumber => $item_id,
480 issue_id => $issue_id,
481 branchcode => $library_id,
482 register_id => $cash_register,
484 $debit_type eq 'OVERDUE'
485 ? ( status => 'UNRETURNED' )
491 # Record the account offset
492 my $account_offset = Koha::Account::Offset->new(
494 debit_id => $line->id,
500 if ( C4::Context->preference("FinesLog") ) {
506 action => "create_$debit_type",
507 borrowernumber => $self->{patron_id},
509 description => $description,
510 amountoutstanding => $amount,
511 debit_type_code => $debit_type,
513 itemnumber => $item_id,
514 manager_id => $user_id,
524 if ( ref($_) eq 'Koha::Exceptions::Object::FKConstraint' ) {
525 if ( $_->broken_fk eq 'debit_type_code' ) {
526 Koha::Exceptions::Account::UnrecognisedType->throw(
527 error => 'Type of debit not recognised' );
540 my $debit = $account->payout_amount(
542 payout_type => $payout_type,
543 register_id => $register_id,
544 staff_id => $staff_id,
545 interface => 'intranet',
547 credits => $credit_lines
551 This method allows an amount to be paid out from a patrons account against outstanding credits.
553 $payout_type can be any of the defined payment_types:
558 my ( $self, $params ) = @_;
560 # Check for mandatory parameters
562 ( 'interface', 'staff_id', 'branch', 'payout_type', 'amount' );
563 for my $param (@mandatory) {
564 unless ( defined( $params->{$param} ) ) {
565 Koha::Exceptions::MissingParameter->throw(
566 error => "The $param parameter is mandatory" );
570 # Check for mandatory register
571 Koha::Exceptions::Account::RegisterRequired->throw()
572 if ( C4::Context->preference("UseCashRegisters")
573 && ( $params->{payout_type} eq 'CASH' )
574 && !defined($params->{cash_register}) );
576 # Amount should always be passed as a positive value
577 my $amount = $params->{amount};
578 unless ( $amount > 0 ) {
579 Koha::Exceptions::Account::AmountNotPositive->throw(
580 error => 'Payout amount passed is not positive' );
583 # Amount should always be less than or equal to outstanding credit
585 my $outstanding_credits =
586 exists( $params->{credits} )
588 : $self->outstanding_credits->as_list;
589 for my $credit ( @{$outstanding_credits} ) {
590 $outstanding += $credit->amountoutstanding;
592 $outstanding = $outstanding * -1;
593 Koha::Exceptions::ParameterTooHigh->throw( error =>
594 "Amount to payout ($amount) is higher than amountoutstanding ($outstanding)"
595 ) unless ( $outstanding >= $amount );
598 my $schema = Koha::Database->new->schema;
602 # A 'payout' is a 'debit'
603 $payout = $self->add_debit(
605 amount => $params->{amount},
607 transaction_type => $params->{payout_type},
608 amountoutstanding => $params->{amount},
609 manager_id => $params->{staff_id},
610 interface => $params->{interface},
611 branchcode => $params->{branch},
612 cash_register => $params->{cash_register}
616 # Offset against credits
617 for my $credit ( @{$outstanding_credits} ) {
618 $credit->apply( { debits => [$payout] } );
619 $payout->discard_changes;
620 last if $payout->amountoutstanding == 0;
624 $payout->status('PAID')->store;
633 my $balance = $self->balance
635 Return the balance (sum of amountoutstanding columns)
641 return $self->lines->total_outstanding;
644 =head3 outstanding_debits
646 my $lines = Koha::Account->new({ patron_id => $patron_id })->outstanding_debits;
648 It returns the debit lines with outstanding amounts for the patron.
650 It returns a Koha::Account::Lines iterator.
654 sub outstanding_debits {
657 return $self->lines->search(
659 amount => { '>' => 0 },
660 amountoutstanding => { '>' => 0 }
665 =head3 outstanding_credits
667 my $lines = Koha::Account->new({ patron_id => $patron_id })->outstanding_credits;
669 It returns the credit lines with outstanding amounts for the patron.
671 It returns a Koha::Account::Lines iterator.
675 sub outstanding_credits {
678 return $self->lines->search(
680 amount => { '<' => 0 },
681 amountoutstanding => { '<' => 0 }
686 =head3 non_issues_charges
688 my $non_issues_charges = $self->non_issues_charges
690 Calculates amount immediately owing by the patron - non-issue charges.
692 Charges exempt from non-issue are:
693 * Res (holds) if HoldsInNoissuesCharge syspref is set to false
694 * Rent (rental) if RentalsInNoissuesCharge syspref is set to false
695 * Manual invoices if ManInvInNoissuesCharge syspref is set to false
699 sub non_issues_charges {
702 #NOTE: With bug 23049 these preferences could be moved to being attached
703 #to individual debit types to give more flexability and specificity.
705 push @not_fines, 'RESERVE'
706 unless C4::Context->preference('HoldsInNoissuesCharge');
707 push @not_fines, ( 'RENT', 'RENT_DAILY', 'RENT_RENEW', 'RENT_DAILY_RENEW' )
708 unless C4::Context->preference('RentalsInNoissuesCharge');
709 unless ( C4::Context->preference('ManInvInNoissuesCharge') ) {
710 my @man_inv = Koha::Account::DebitTypes->search({ is_system => 0 })->get_column('code');
711 push @not_fines, @man_inv;
714 return $self->lines->search(
716 debit_type_code => { -not_in => \@not_fines }
718 )->total_outstanding;
723 my $lines = $self->lines;
725 Return all credits and debits for the user, outstanding or otherwise
732 return Koha::Account::Lines->search(
734 borrowernumber => $self->{patron_id},
739 =head3 reconcile_balance
741 $account->reconcile_balance();
743 Find outstanding credits and use them to pay outstanding debits.
744 Currently, this implicitly uses the 'First In First Out' rule for
745 applying credits against debits.
749 sub reconcile_balance {
752 my $outstanding_debits = $self->outstanding_debits;
753 my $outstanding_credits = $self->outstanding_credits;
755 while ( $outstanding_debits->total_outstanding > 0
756 and my $credit = $outstanding_credits->next )
758 # there's both outstanding debits and credits
759 $credit->apply( { debits => [ $outstanding_debits->as_list ] } ); # applying credit, no special offset
761 $outstanding_debits = $self->outstanding_debits;
774 Kyle M Hall <kyle.m.hall@gmail.com>
775 Tomás Cohen Arazi <tomascohen@gmail.com>
776 Martin Renvoize <martin.renvoize@ptfs-europe.com>