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.