The EPI - E-Payment Interface

 

Overview | Concept | Licensing | Download | Installation | Sample Code | FAQ
Products | Scripts | Services | Tutorials | Books | Links | Contact | Bulletin Board

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

AuthorizeNet | BluePay | CyberCash | Echo Inc. | ESec | FirePay | GO Software(PCCharge)

iBill | Innovative Gateway | IntelliPay | Iongate | IPayment | LinkPoint | NovaInfo | PayBill

PayPal | PaySystems | Plug-n-Pay | Qenta | Skipjack | TeleCash | VeriSign | WorldPay

PayPal

PayPal is an US based company, but has a presence in some other countries as well, mostly European countries. As of this writing, PayPal only supports transactions in US dollars, but they plan to use other currencies in the future.

 

What you need to start

The only authentication token required for PayPal is the email address that you used to register your account.

 

Gateway Configuration Data

The PayPal product homepage is under: http://www.paypal.com/

This package uses a SSL backlink method to submit the data to the url:

https://ww.paypal.com/cgi-bin/webscr

PayPal supports user to user transactions, a PayPal own cart feature, and the "web_accept" method, which is the method used by EPI.

You will need the following software installed:

Net::SSLeay v1.15
OpenSSL v0.9.6c

Please check the Net::SSLeay web page for the correct version required:
http://symlabs.com/Net_SSLeay/

For the people that don't have Net::SSLeay installed (NT folks),
there is an alternative submission method using:

LWP::UserAgent
Crypt::SSLeay

Please see the main installation instructions for more information on configuring the SSL modules.

You will have to enable the IPN (Instant Payment Notification) on the PayPal site, and use there the URL to your main script

 

Code to use for The CITY Shop

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

-MERCHANT_DATA_MAP => {
  'PayPal'     => {
  -GATEWAY_NAME      => 'PayPal',
  -MERCHANT_ID       => 'myemail@mydomain.com',
  -EXTERNAL_METHOD   => 1,
  -GATEWAY_CONNECT_METHOD => 'SubmitLWPUserAgent', # or SubmitNetSSLeay
  },
},
...

For The CITY Shop users, remember that you will have to configure the IPN on the PayPal site, to use the shop URL for the success/cancel links. Enter there the shop url without any other parameters, since this will be used in a POST.

Please note that you will also have to define in the This.pm ein parameter that will be passed by the shop to the -GATEWAY_CONNECT_METHOD, in the following format:

-COMMON_REMOTE_ACCESS_METHOD => 'SubmitLWPUserAgent',

This parameter is needed because at the time of processing the callback, there is no information about what shop called this action, and thus the information in the ShopSetup.pm is not accessible.

For the CITY Shop, the IPN link to be used is the shop base link, i.e. :

http://www.mydomain.com/cgi-bin/store/store.cgi

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 PayPal 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.

-GATEWAY_CONNECT_METHOD
This is the same as the key used by the "normal" payment gateways, and points to the method used to connect to the gateway site, in order to finalize the transaction. The allowed values are "SubmitLWPUserAgent" and "SubmitNetSSLeay"

 

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

-MERCHANT_LOGO_URL
If you want to display a logo of your store on the PayPal 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 "PAYPAL.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. It is not needed if you configured an URL in the IPN settings for your PayPal account.

-GATEWAY_CANCEL_LINK
This is the URL of the script that will be loaded/pointed to if the transaction is cancelled by the user. It is not needed if you configured an URL in the IPN settings for your PayPal account.

-IGNORE_BROWSER_CALLBACK_POSTS
This key is a flag, which you can set on "1" when you want to avoid duplicate order processing. EPI currently does not make use of it internally, but you should use it as in the example below.
The way IPN is currently configured by PayPal, even if the PayPal site performs a hidden post, they also give the customer the similar submission option in the browser.
When the customer clicks the "Continue" button, your script will get a similar query with the hidden post, which you will have to ignore, if you performed the first one correctly.
The CITY Shop implements as of version 1.3 a protection mechanism using this key, and we include an example of usage in the code below.

 

 

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 PayPal 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 PayPal, as used by the shop in the routine PaymentPayPalVIEW.pm:

...
my $OrderID      = time();
my $Total        = '10.00';
my $CustomField  = 'Shop custom data';
my $MerchantData = {
  -GATEWAY_NAME         => 'PayPal',
  -MERCHANT_ID          => 'myemail@mydomain.com',
  -MERCHANT_LOGO_URL    => 'https://www.mydomain.com/images/shops/city/storesmalllogo.gif',
  -GATEWAY_SUCCESS_LINK => 'http://www.mydomain.com/cgi-bin/process_callback.cgi',
  -GATEWAY_CANCEL_LINK  => 'http://www.mydomain.com/cgi-bin/process_callback.cgi',
  -EXTERNAL_METHOD      => 1,
};
use EPI;
my $Merchant = new EPI($MerchantData);
my $MForm = {
  -ORDER_DESCRIPTION    => 'My Custom Order',
  -ORDER_NUMBER         => $OrderID,
  -ORDER_AMOUNT         => $Total,
  -TRANSACTION_DATA     => $CustomField,
};
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 PayPal!"></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, PayPal returns a hidden POST, using the IPN (Instant Payment Notification), 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         => 'PayPal',
  -MERCHANT_ID          => 'myemail@mydomain.com',
  -EXTERNAL_METHOD      => 1,
  -LOG_ACTIVITY         => 1,
  -LOG_FILE_PATH             => './logs',
  -GATEWAY_CONNECT_METHOD => 'SubmitLWPUserAgent', # or SubmitNetSSLeay
  -IGNORE_BROWSER_CALLBACK_POSTS => 1,
};
use EPI;
my $Merchant = new EPI($MerchantData); 
my $Response;
my $Error = "Browser validation not supported";
if (! $Merchant->{-IGNORE_BROWSER_CALLBACK_POSTS} || $IsBrowser) {
  $Response = $Merchant->_process_callback($FX);
  $Error    = $Response->{-ERROR} || '';
}
if (! $Error && $Response->{-OK}) {
  my $TStatus = $Response->{-TRANSACTION_STATUS};
  if ($TStatus eq 'COMPLETED' || $TStatus eq 'PENDING') {
# put here code to enable order processing
  }
  elsif ($TStatus eq 'DENIED' || $TStatus eq 'FAILED') {
# put here code to enable order cancelling
  }
  else {
    $Error = 'Transaction Status Unknown';
  }
}
else {
  $Error = $Response->{-ERROR} || '';
}

if ($Error) {
  print $Error;
}
else {
  my $CustomField = $Response->{-TRANSACTION_DATA} || '';
  print 'Transaction OK, here is the custom field: '.$CustomField;
}
...