Nightmedia - EPI WorldPay Interface

The EPI - E-Payment Interface

Please follow the links below to read the documentation specific to your gateway:

WorldPay

WorldPay is a company based in Great Britain, with presence in multiple other countries. WorldPay supports transactions multiple currencies, and accepts credit card payments, as well as direct debit.

What you need to start

You receive from WorldPay a merchant ID, and eventually separate account ID's for the customer accounts. Please refer to the WorldPay online docs.

Gateway Configuration Data

The WorldPay product homepage is under: http://www.worldpay.com/

The administration server is under: http://support.worldpay.com/admin/

You will have to configure on the WorldPay site the URL for the callback, to use the shop URL for the success/cancel links. Since the shop passes that parameter as "MC_callback", you should configure your callback URL on the WorldPay site as follows:

http://<WPDISPLAY ITEM=MC_callback>

You also have to enable the callback, by checking the following box: "Callback enabled"
You should also enable the printout of the receipt, by checking the box: "Use callback response"

As a result, WorldPay will submit the callback and use your script output to build the final receipt.

Code to use for The CITY Shop

This is the code that you will put/modify in the ShopSetup.pm:

-MERCHANT_DATA_MAP => {
  'WorldPay'     => {
  -GATEWAY_NAME        => 'WorldPay',
  -MERCHANT_ID         => 'xxxxx',
  -EXTERNAL_METHOD     => 1,
  },
},
...

If you configure this for The CITY Shop, that is all you need to know, and you can return to the installation instructions.

Description of the used parameters:

-MERCHANT_ID
This is the WorldPay email that you want to use to receive money.

-EXTERNAL_METHOD
This will ALWAYS have to stay on 1, and means that this gateway uses an alternate submission method. It is very important for The CITY Shop to help determine the right course of action, but is not used by the EPI internally.

Here are some extra parameters that you can use if you implement the EPI in other scripts:

-MERCHANT_ACCOUNT_ID
Specifies which customer account should receive funds for this payment. The WorldPay server tries accId1. If this is invalid for any reason, it selects the first valid account it can find based on the
testMode value and the currencies available. There is no need to specify accounts, but this is useful if you have multiple live accounts for different purposes.

-MERCHANT_LOGO_URL
If you want to display a logo of your store on the WorldPay payment page, you can provide it in this key. Please be aware that this URL should be a secure URL, to avoid browser errors.

-LOG_ACTIVITY
This is a flag that you can set on "1" if you want to log the callbacks

-LOG_FILE_PATH
This is the path where the log file will be created. Note that this is a path only, and the script will create there a file named "WORLDPAY.log"

-TRANSACTION_DATA
For passing back specific parameters, you can assign that value to this key, and the same value will be returned to you by the gateway callback post, in the response hash.

-GATEWAY_SUCCESS_LINK
This is the URL of the script that will be loaded/pointed to if the transaction is successful.

Sample code for your custom scripts

The CITY Shop automatically uses the right combination of routines, the code that follows is not intended for use in The CITY Shop!

Please be aware that the example code that follows is not a full script. Implementing this code in your script might need a certain level of customization to make it work, i.e. changing variable names, executing certain routines, printing results, etc..

Since the WorldPay gateway uses an external/remote payment method, you will not use the default method to submit a transaction, as the "normal" gateways.

STEP 1

First you print on your screen a form that will be redirecting the user to WorldPay, as used by the shop in the routine PaymentWorldPayVIEW.pm:

...
my $OrderID      = time();
my $Total        = '10.00';
my $OCurrency    = 'USD';
my $CustomField  = 'Shop custom data';
my $UAddress     = '101 Main St.';
my $UName        = 'John Doe';
my $UAddress     = '101 Main St';
my $UCity        = 'Sacramento';
my $UZip         = '95814';
my $UState       = 'CA';
my $UCountry     = 'US';
my $UPhone       = '(510)985 6733';
my $UEmail       = 'user@myhost.com';

my $MerchantData = {
  -GATEWAY_NAME         => 'WorldPay',
  -MERCHANT_ID          => 'xxxxx',
  -MERCHANT_ACCOUNT_ID  => '12', # OPTIONAL
  -MERCHANT_LOGO_URL    => 'https://www.mydomain.com/images/shops/city/storesmalllogo.gif',
  -GATEWAY_SUCCESS_LINK => 'http://www.mydomain.com/cgi-bin/process_callback.cgi',
  -EXTERNAL_METHOD      => 1,
};
use EPI;
my $Merchant = new EPI($MerchantData);
my $MForm = {
  -ORDER_NUMBER         => $OrderID,
  -ORDER_CURRENCY       => $OCurrency,
  -ORDER_AMOUNT         => $Total,
  -TRANSACTION_DATA     => $CustomField,
# The following parameters are optional:
  -ORDER_DESCRIPTION    => 'My Custom Order',
  -USER_FULL_NAME       => $UName,
  -USER_ADDRESS         => $UAddress,
  -USER_CITY            => $UCity,
  -USER_STATE           => $UState,
  -USER_ZIP             => $UZip,
  -USER_COUNTRY         => $UCountry,
  -USER_PHONE           => $UPhone,
  -USER_EMAIL           => $UEmail,
};

my %FormData = $Merchant->_prepare_form_data($MForm);
print qq~<form action="$FormData{-ACTION}" method="$FormData{-METHOD}">$FormData{-HIDDEN}
<input type=submit name="Submit" value="Pay With WorldPay!"></form>~;

...

There is an alternate way to display the form, if you don't need any fancy in the form display. You can use the method in scalar context, printing the result directly:

my $FormData = $Merchant->_prepare_form_data($MForm);
print $FormData;

STEP 2

Then, WorldPay returns a hidden POST, using the URL described by you in the "MC_callback" field and your script should use the following method, very similar with the one used by the shop in the PaymentLib.pm. Note that the form input data is contained in the anonymous hash $FX.

...
my $IsBrowser = $ENV{'HTTP_USER_AGENT'} ? 1 : 0;
my $MerchantData = {
  -GATEWAY_NAME         => 'WorldPay',
  -MERCHANT_ID          => 'xxxxx',
  -EXTERNAL_METHOD      => 1,
  -LOG_ACTIVITY         => 1,
  -LOG_FILE_PATH             => './logs',
};
use EPI;
my $Merchant = new EPI($MerchantData); 
my $Response = $Merchant->_process_callback($FX);
if ($Response->{-OK}) {
# put here code to enable order processing
  my $CustomField = $Response->{-TRANSACTION_DATA} || '';
  print 'Transaction OK, here is the custom field: '.$CustomField;
}
else {
  print $Response->{-ERROR};
}
...