When a refund is performed against a completed order, you can elect to have the system call a URL on your own site with details of the refund.

Activating the Refund Notifier

To activate the Refund Notifier, log into your SWREG account and select the Edit Your Author Details option. Scroll down until you see the following option :-

Enter the full URL of your callback including the http or https prefix. When a refund occurrs, the system will POST the details of the transaction to the specified URL, and collect the response (see below). To stop the Refund Notifier from calling your site, simply empty the field.

Fields sent to the Refund Notifier

Security & Identification

• shop_id - You should check this to ensure it's for your shop the notification is being sent. You can also use this field if you have more than one shop and wish to use the same callback for both.
• security - This field will contain the Sales Notification E-Mail Address which you have set up in your author details page. You should validate this to ensure the notification has come from SWREG.

Refund Identification

• order_no - The order number of the order being refunded.
• notify_type - The type of refund being performed. (see below for more details).

Customer Identification

• name - Customers full name.
• add1 - Street address line 1.
• add2 - Street address line 2.
• add3 - City.
• add4 - State/Province.
• add5 - Zip/Postal Code.
• country - Country.
• email - Primary E-Mail address.
• ccmail - Secondary or CC E-Mail address.
• telephone - Telephone number.
• company_name - Company Name.
• d_name - Delivery full name.
• d_add1 - Delivery street address line 1.
• d_add2 - Delivery street address line 2.
• d_add3 - Delivery city.
• d_add4 - Delivery state/province.
• d_add5 - Delivery zip/postal code.
• d_country - Delivery country.
• d_company_name - Delivery telephone number.

Notification Types

The following notification types are sent to the Notification Callback.

• full_refund - This indicates that a full refund has been performed on the specified order. The following extra fields are sent when a full refund occurrs (all values will be in the base currency of the machine).
  • net_total - The total without tax/surcharge of the order.
  • vat - The total VAT or State tax applied to the order.
  • surcharge - Any surcharges applied.
    
    
• vpdq - This indicates that a partial refund has been performed on the specified order (a partial refund could be for the full amount of the order, or seemingly more than the full amount if the customer was overcharged) by an SWREG administrator. These refunds differ from the full_refund in that they are used for many different purposes and may not necessarily mean that the customer should no longer be able to use your product. The following extra fields are sent when a vpdq refund occurs.
  • amount - The amount refunded.
  • currency - The currency of the amount refunded (USD, GBP, EUR or CAD).

What your refund notifier should return

In order for our system to correctly identify that your refund notifier has been correctly called and the notification processed, it should return a minimum of 2 characters, "OK". Anything after this can be an informational message upto 128 characters long which will be written to our logs.

Eg. OK: Not my shop ID

What happens when an error occurs?

When an error occurs, or "OK" is not returned from the callback, then the notification is placed on a queue and will be retried a short while later. After a few attempts the notification will be discarded.

In addition, if you have set up a Keygen Failure E-Mail Address in your author details section, an E-Mail will be sent to that address with the details of the failure.

Example Code

#!/usr/bin/perl

use CGI;

#---------------
# Some constants
#---------------
use constant MY_SHOP_ID			=> 1234;
use constant MY_SALES_EMAIL		=> 'sales@my-web-site.com';

#------------------------------------
# Setup CGI hash & output html header
#------------------------------------
my $cgi = new CGI;
print $cgi->header();

#------------------------------------
# Extract the parameters
#------------------------------------
my $notify_type = $cgi->param('notify_type');
my $shop_id = $cgi->param('shop_id');
my $order_no = $cgi->param('order_no');
my $email = $cgi->param('email');
my $ccmail = $cgi->param('ccmail');

my $name = $cgi->param('name');
my $add1 = $cgi->param('add1');
my $add2 = $cgi->param('add2');
my $add3 = $cgi->param('add3');
my $add4 = $cgi->param('add4');
my $add5 = $cgi->param('add5');
my $country = $cgi->param('country');
my $telephone = $cgi->param('telephone');
my $company_name = $cgi->param('company_name');

my $d_name = $cgi->param('d_name');
my $d_add1 = $cgi->param('d_add1');
my $d_add2 = $cgi->param('d_add2');
my $d_add3 = $cgi->param('d_add3');
my $d_add4 = $cgi->param('d_add4');
my $d_add5 = $cgi->param('d_add5');
my $d_country = $cgi->param('d_country');
my $d_company_name = $cgi->param('d_company_name');

my $security = $cgi->param('security');

my $rv = process_refund();

print "OK" if ($rv == 0);
print "OK: Unknown notify type" if ($rv == 1);
print "OK: Not my shop" if ($rv == 2);
print "OK: Not my sales email address" if ($rv == 3);

exit;

sub process_refund
{
	#-------------------------------------
	# Check that the refund is for my shop
	#-------------------------------------
	return 2 if ($shop_id != MY_SHOP_ID);
	return 3 if ($security != MY_SALES_EMAIL);

	#--------------------------
	# Handle full order refunds
	#--------------------------
	if ($notify_type eq 'full_refund')
	{
		my $net_total = $cgi->param('net_total');
		my $vat = $cgi->param('vat');
		my $surcharge = $cgi->param('surcharge');

		# Handle the refund notification

		return 0;
	}

	#--------------------------
	# Handle vpdq order refunds
	#--------------------------
	if ($notify_type eq 'vpdq')
	{
		my $amount = $cgi->param('amount');
		my $currency = $cgi->param('currency');

		# Handle the refund notification

		return 0;
	}
	return 1;
}