Freeside:3: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 ] [ -v ] 
                        [ -X reasonnum ] 
                        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 get_returns() method.  For an example, see 
 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 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.

 -v: Be verbose.
 
 -X: Automatically cancel all packages belonging to customers whose 
     payments were returned.  Requires a cancellation reasonnum 
     (from FS::reason).

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.

SEE ALSO

Business::OnlinePayment, FS::cust_pay