freeside-void-payments - Automatically void a list of returned payments.
freeside-void-payments [ -f file | [ -s start-date ] [ -e end-date ] ] [ -r 'reason' ] [ -g gatewaynum | -a agentnum ] [ -c ] [ -v ] [ -X reasonnum ] user
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).
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'
Most payment gateways don't support it.