Freeside:1.7:Documentation:Developer/bin/freeside-void-payments

NAME

freeside-void-payments - Automatically void a list of returned payments.

SYNOPSIS

 freeside-void-payments [ -f file | [ -s start-date ] [ -e end-date ] ] [ -r 'reason' ] [ -g gatewaynum | -a agentnum ] [ -c ] user

DESCRIPTION

Voids payments that were returned by the payment processor. Can be run periodically from crontab or manually after receiving a list of returned payments. Normally this is a meaningful operation only for electronic checks.

This script voids payments based on the combination of gateway (see FS::payment_gateway) and authorization number, since this is generally how the processor will identify them later.

 -f: Read the list of authorization numbers from the specified file.  
     If they are not from the default payment gateway, -g or -a 
     must be given to identify the gateway.
     
 If -f is not given, the script will attempt to contact the gateway 
 and download a list of returned transactions.  To support this, 
 the Business::OnlinePayment module for the processor must implement 
 the I<get_returns()> method.  For an example, see 
 L<Business::OnlinePayment::WesternACH>.

 -s, -e: Specify the starting and ending dates for the void list.  
     This has no effect if -f is given.  The end date defaults to 
     today, and the start date defaults to one day before the end date.

 -r: The reason for voiding the payments, to be stored in the database.

 -g: The L<FS::payment_gateway> number for the gateway that handled 
     these payments.  If -f is not given, this determines which 
     gateway will be contacted.  This overrides -a.

 -a: The agentnum whose default gateway will be used.  If neither -a 
     nor -g is given, the system default gateway will be used.

 -c: Use the default gateway for check transactions rather than 
     credit cards.

A warning will be emitted for each transaction that can't be found. This may happen if it's already been voided, or if the gateway doesn't match.

EXAMPLE

Given 'returns.txt', which contains one authorization number on each line, provided by your default e-check processor:

 freeside-void-payments -f returns.txt -c -r 'Returned check'

If your default processor is Western ACH, which supports automated returns processing, this voids all returned payments since 2009-06-01:

 freeside-void-payments -r 'Returned check' -s 2009-06-01

This, in your crontab, will void returned payments for the last day at 8:30 every morning:

 30 8 * * * /usr/local/bin/freeside-void-payments -r 'Returned check'

BUGS

Most payment gateways don't support it, making the script largely useless.

SEE ALSO

Business::OnlinePayment, FS::cust_pay