.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Vend::Payment::SagePay 3pm"
.TH Vend::Payment::SagePay 3pm "2011-03-09" "perl v5.14.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "Interchange Sagepay Support"
.IX Header "Interchange Sagepay Support"
Vend::Payment::SagePay \f(CW$Revision:\fR 0.8.7 $
.PP
http://kiwi.zolotek.net is the home page with the latest version.
.SH "This package is for the 'SagePay Direct' payment system."
.IX Header "This package is for the 'SagePay Direct' payment system."
Note that their 'Direct' system is the only one which leaves the customer on
your own site and takes payment in real time. Their other systems, eg Terminal
or Server, do not require this module.
.SH "Quick Start Summary"
.IX Header "Quick Start Summary"
1 Place this module in <IC_root>/lib/Vend/Payment/SagePay.pm
.PP
2 Call it in interchange.cfg with:
    Require module Vend::Payment::SagePay
.PP
3 Add into variable.txt (tab separated):
    \s-1MV_PAYMENT_MODE\s0   sagepay
  Add a new route into catalog.cfg (options for the last entry in parentheses):
    Route sagepay id YourSagePayID
    Route sagepay host live.sagepay.com (test.sagepay.com)
    Route sagepay currency \s-1GBP\s0 (\s-1USD\s0, \s-1EUR\s0, others, defaults to \s-1GBP\s0)
    Route sagepay txtype \s-1PAYMENT\s0 (\s-1AUTHENTICATE\s0, \s-1DEFERRED\s0)
    Route sagepay available yes (no, empty)
    Route sagepay logzero yes (no, empty)
    Route sagepay logorder yes (no, empty)
    Route sagepay logsagepay yes (no, empty)
    Route sagepay applyavscv2 '0': if enabled then check, and if rules apply use.
                    '1': force checks even if not enabled; if rules apply use.
                    '2': force \s-1NO\s0 checks even if enabled on account.
                    '3': force checks even if not enabled; do \s-1NOT\s0 apply rules.
    Route sagepay giftaidpayment 0 (1 to donate tax to Gift Aid)
.PP
4 Create a new locale setting for en_GB as noted in \*(L"item currency\*(R" below, and copy the
public space interchange/en_US/ directory to a new interchange/en_GB/ one. Ensure that any
other locales you might use have a correctly named directory as well. Ensure that this locale
is found in your version of locale.txt (and set up \s-1GB\s0 as opposed to \s-1US\s0 language strings to taste).
.PP
5 Create entry boxes on your checkout page for: 'mv_credit_card_issue_number', 'mv_credit_card_start_month',
\&'mv_credit_card_start_year', 'mv_credit_card_type' and  'mv_credit_card_cvv2'.
.PP
6 The new fields in \s-1API\s0 2.23 are: BillingAddress, BillingPostCode, DeliveryAddress, DeliveryPostCode,
BillingFirstnames, BillingSurname, DeliveryFirstnames, DeliverySurname, ContactNumber,ContactFax,CustomerEmail.
CustomerName has been removed. Billing and Delivery State must be sent if the destination country is the \s-1US\s0, otherwise
they are not required. State must be only 2 letters if sent. Other fields may default to a space if there
is no proper value to send, though this may conflict with your \s-1AVS\s0 checking rules. SagePay currently 
accept a space as of time of writing \- if they change this without changing the \s-1API\s0 version then send
either a series of '0' or '\-' characters to stop their error messages.
.PP
7. Add a page in pages/ord/, tdsfinal.html, being a minimal page with only the header and side bar,
and in the middle of the page put:
[if scratch acsurl]
	  <tr>
		<td align=center height=600 valign=middle colspan=2>
		  <iframe src=\*(L"_\|_CGI_URL_\|_/ord/tdsauth.html\*(R" frameborder=0 width=600 height=600></iframe>
		</td>
	  </tr>
[/if]
.PP
Add a page in pages/ord/, tdsauth.html, consisting of this:
<body onload=\*(L"document.form.\fIsubmit()\fR;\*(R">
<\s-1FORM\s0 name=\*(L"form\*(R" action=\*(L"[scratchd acsurl]\*(R" method=\*(L"\s-1POST\s0\*(R" />
<input type=\*(L"hidden\*(R" name=\*(L"PaReq\*(R" value=\*(L"[scratch pareq]\*(R" />
<input type=\*(L"hidden\*(R" name=\*(L"TermUrl\*(R" value=\*(L"[scratch termurl]\*(R" />
<input type=\*(L"hidden\*(R" name=\*(L"\s-1MD\s0\*(R" value=\*(L"[scratch md]\*(R" />
</form>
</body>
along with whatever <noscript> equivalent you want. This will retrieve the bank's page within the iframe.
.PP
Add a page in pages/ord/, tdsreturn.html, consisting of this:
	[charge route=\*(L"sagepay\*(R" sagepayrequest=\*(L"3dsreturn\*(R"]
	<p>
	   <blockquote>
        <font color=\*(L"_\|_CONTRAST_\|_\*(R">
                [error all=1 keep=1 show_error=1 show_label=1 joiner=\*(L"<br>\*(R"]
        </font>
       </blockquote>
.PP
The iframe in 'tdsfinal' will be populated with the contents of 'tdsauth', and the javascript will
automatically display the bank's authentication page. When the customer clicks 'Submit' at the bank's
page, the iframe contents will be replaced with the 'tdsreturn' page, which will complete the route 
and display the receipt inside the iframe. If the customer clicks 'cancel' at the bank, then this 
\&'tdsreturn' page will stay put and display whatever message you have put there along with the error message. 
The value of [scratch tds] is set true for a 3DSecure transaction only, so can be used for messages
etc on the receipt page.
.PP
8. When running a card through 3DSecure, the route is run twice: firstly to Sagepay who check whether or
not the card is part of 3DSecure \- if it is they send the customer to the bank's authentication page
and upon returning from that the route must be run a second time to send the authentication results to
Sagepay. The second run is initiated from the 'ord/tdsreturn' page, not from etc/log_transaction as it normally
would be. To handle this change to the normal system flow you need to alter log_transaction to make the 
call to the payment module conditional,ie, wrap the following code around the \*(L"[charge route...]\*(R" call 
found in ln 172 (or nearby):
	[if scratchd mstatus eq success]
	[tmp name=\*(L"charge_succeed\*(R"][scratch order_id][/tmp]
	[else]
	[tmp name=\*(L"charge_succeed\*(R"][charge route=\*(L"[var \s-1MV_PAYMENT_MODE\s0]\*(R" amount=\*(L"[scratch tmp_remaining]\*(R" order_id=\*(L"[value mv_transaction_id]\*(R"][/tmp]
	[/else]
	[/if]
If the first call to Sagepay returns a request to send the customer to the 3DSecure server, then \s-1IC\s0 will 
write a payment route error to the error log prior to sending the customer there. This error stops the
route completing and lets the 3DSecure process proceed as it should. This error is not raised if the card
is not part of 3DSecure, and instead the route completes as it normally would.
.PP
Also add this line just after '&final = yes' near the end of the credit_card section of etc/profiles.order:
	&set=mv_payment_route sagepay
.PP
9. Add these new fields into log_transaction, to record the values returned from Sagepay (these will be
key in identifying transactions and problems in any dispute with them):
.PP
mv_credit_card_type: [calc]$Session\->{payment_result}{CardType}[/calc]
mv_credit_card_issue_number: [value mv_credit_card_issue_number]
txtype:  [calc]$Session\->{payment_result}{TxType};[/calc]
vpstxid: [calc]$Session\->{payment_result}{VPSTxID};[/calc]
txauthno: [calc]$Session\->{payment_result}{TxAuthNo};[/calc]
securitykey: [calc]$Session\->{payment_result}{SecurityKey};[/calc]
vendortxcode:  [calc]$Session\->{payment_result}{VendorTxCode};[/calc]
avscv2: [calc]$Session\->{payment_result}{\s-1AVSCV2\s0};[/calc]
addressresult:[calc]$Session\->{payment_result}{AddressResult};[/calc]
postcoderesult: [calc]$Session\->{payment_result}{PostCodeResult};[/calc]
cv2result: [calc]$Session\->{payment_result}{CV2Result};[/calc]
securestatus:[calc]$Session\->{payment_result}{SecureStatus};[/calc]
pares: [calc]$Session\->{payment_result}{PaRes};[/calc]
md: [calc]$Session\->{payment_result}{\s-1MD\s0};[/calc]
cavv: [calc]$Session\->{payment_result}{\s-1CAVV\s0};[/calc]
and add these into your MySQL or Postgres transactions table, as type varchar(128) except for 'pares'
which should be type 'text'.
.PP
Note that there is no 'TxAuthNo' returned for a successful \s-1AUTHENTICATE\s0.
.SH "PREREQUISITES"
.IX Header "PREREQUISITES"
.Vb 3
\&  Net::SSLeay
\&    or
\&  LWP::UserAgent and Crypt::SSLeay
\&
\&  wget \- a recent version built with SSL and supporting the \*(Aqconnect\*(Aq timeout function.
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The Vend::Payment::SagePay module implements the \fISagePay()\fR routine for use with
Interchange. It is _not_ compatible on a call level with the other Interchange
payment modules \- SagePay does things rather differently.
.PP
To enable this module, place this directive in \f(CW\*(C`interchange.cfg\*(C'\fR:
.PP
.Vb 1
\&    Require module Vend::Payment::SagePay
.Ve
.PP
This \fImust\fR be in interchange.cfg or a file included from it.
.PP
Make sure CreditCardAuto is off (default in Interchange demos).
.SH "The active settings."
.IX Header "The active settings."
The module uses several of the standard settings from the Interchange payment routes.
Any such setting, as a general rule, is obtained first from the tag/call options on
a page, then from an Interchange order Route named for the mode in catalog.cfg,
then a default global payment variable in products/variable.txt, and finally in
some cases a default will be hard-coded into the module.
.IP "Mode" 4
.IX Item "Mode"
The mode can be named anything, but the \f(CW\*(C`gateway\*(C'\fR parameter must be set
to \f(CW\*(C`sagepay\*(C'\fR. To make it the default payment gateway for all credit card
transactions in a specific catalog, you can set in \f(CW\*(C`catalog.cfg\*(C'\fR:
.Sp
.Vb 3
\&    Variable   MV_PAYMENT_MODE  sagepay
\&or in variable.txt:
\&    MV_PAYMENT_MODE sagepay (tab separated)
.Ve
.Sp
if you want this to cooperate with other payment systems, eg PaypalExpress, then see the documentation
that comes with that system \- it should be fully explained there.
.IP "id" 4
.IX Item "id"
Your SagePay vendor \s-1ID\s0, supplied by SagePay when you sign up. Various ways to state this:
in variable.txt:
    \s-1MV_PAYMENT_ID\s0   YourSagePayID Payment
or in catalog.cfg either of:
    Route sagepay id YourSagePayID
    Variable \s-1MV_PAYMENT_ID\s0      YourSagePayID
or on the page
    [charge route=sagepay id=YourSagePayID]
.IP "txtype" 4
.IX Item "txtype"
The transaction type is one of: \s-1PAYMENT\s0, \s-1AUTHENTICATE\s0, \s-1DEFERRED\s0 for an initial purchase
through the catalogue, and then can be one of: \s-1AUTHORISE\s0, \s-1REFUND\s0, \s-1RELEASE\s0, \s-1VOID\s0, \s-1ABORT\s0 for payment
operations through the virtual terminal.
.Sp
The transaction type is taken firstly from a dynamic variable in the page, meant
primarily for use with the 'virtual payment terminal', viz: 'transtype' in a select box
though this could usefully be taken from a possible entry in the products database
if you have different products to be sold on different terms; then falling back to
a 'Route txtype \s-1PAYMENT\s0' entry in catalog.cfg; then falling back to a global
variable in variable.txt, eg '\s-1MV_PAYMENT_TXTYPE\s0 \s-1PAYMENT\s0 Payment'; and finally
defaulting to '\s-1PAYMENT\s0' hard-coded into the module. This variable is returned to
the module and logged using the value returned from SagePay, rather than a value from
the page which possibly may not exist.
.IP "available" 4
.IX Item "available"
If 'yes', then the module will check that the gateway is responding before sending the transaction.
If it fails to respond within 9 seconds, then the module will go 'off line' and log the transaction
as though this module had not been called. It will also log the txtype as '\s-1OFFLINE\s0' so that you
know you have to put the transaction through manually later (you will need to capture the card
number to do this). The point of this is that your customer has the transaction done and dusted,
rather than being told to 'try again later' and leaving for ever. If not explicitly 'yes',
defaults to 'no'. \s-1NB:\s0 if you set this to 'yes', then add into the etc/report that is sent to you:
Txtype = [calc]$Session\->{payment_result}{TxType};[/calc]. Note that you need to have
a recent version of wget which supports '\-\-connect\-timeout' to run this check. Note also that,
as this transaction has not been logged anywhere on the SagePay server, you cannot use their
terminal to process it. You must use a virtual terminal which includes a function for this purpose,
and updates the existing order number with the new payment information returned from SagePay. Note
further that if you have SagePay set up to require the \s-1CV2\s0 value, then virtual terminal should disable
\&\s-1CV2\s0 checking at run-time by default for such a transaction (logging the \s-1CV2\s0 value breaks Visa/MC
rules and so it can't be legally available for this process).
.IP "logzero" 4
.IX Item "logzero"
If 'yes', then the module will log a transaction even if the amount sent is zero (which the
gateway would normally reject). The point of this is to allow a zero amount in the middle of a
subscription billing series for audit purposes. If not explicitly 'yes', defaults to 'no'.
Note: this is only useful if you are using an invoicing system or the Payment Terminal, both of which
by-pass the normal \s-1IC\s0 processes. \s-1IC\s0 will allow an item to be processed at zero total price but simply
bypasses the gateway when doing so.
.ie n .IP "logempty If 'yes, then if the response from SagePay is read as empty (ie, zero bytes) then the module will use the VendorTxID to check on the Sagepay txstatus page to see if that transaction has been logged. If it has then the result found on that page will be used to push the result to either success or failure and log accordingly. There are two markers set to warn of this: $Session\->{payment_result}{TxType} will be \s-1NULL\s0, $Session\->{payment_result}{StatusDetail} will be: '\s-1UNKNOWN\s0 status \- check with SagePay before dispatching goods' and you should include these into the report emailed to you. It will also call a logorder Usertag to log a backup of the order: if you don't already have this then get it from ftp.zolotek.net/mv/logorder.tag" 4
.el .IP "logempty If 'yes, then if the response from SagePay is read as empty (ie, zero bytes) then the module will use the VendorTxID to check on the Sagepay txstatus page to see if that transaction has been logged. If it has then the result found on that page will be used to push the result to either success or failure and log accordingly. There are two markers set to warn of this: \f(CW$Session\fR\->{payment_result}{TxType} will be \s-1NULL\s0, \f(CW$Session\fR\->{payment_result}{StatusDetail} will be: '\s-1UNKNOWN\s0 status \- check with SagePay before dispatching goods' and you should include these into the report emailed to you. It will also call a logorder Usertag to log a backup of the order: if you don't already have this then get it from ftp.zolotek.net/mv/logorder.tag" 4
.IX Item "logempty If 'yes, then if the response from SagePay is read as empty (ie, zero bytes) then the module will use the VendorTxID to check on the Sagepay txstatus page to see if that transaction has been logged. If it has then the result found on that page will be used to push the result to either success or failure and log accordingly. There are two markers set to warn of this: $Session->{payment_result}{TxType} will be NULL, $Session->{payment_result}{StatusDetail} will be: 'UNKNOWN status - check with SagePay before dispatching goods' and you should include these into the report emailed to you. It will also call a logorder Usertag to log a backup of the order: if you don't already have this then get it from ftp.zolotek.net/mv/logorder.tag"
If the result is not found on that txstatus page then the result is forced to 'failure' and the transaction 
shown as failed to the customer.
.IP "card_type" 4
.IX Item "card_type"
SagePay requires that the card type be sent. Valid types are: \s-1VISA\s0, \s-1MC\s0, \s-1AMEX\s0, \s-1DELTA\s0, \s-1SOLO\s0, \s-1MAESTRO\s0, \s-1UKE\s0,
\&\s-1JCB\s0, \s-1DINERS\s0 (\s-1UKE\s0 is Visa Electron issued in the \s-1UK\s0).
.Sp
You may display a select box on the checkout page like so:
.Sp
.Vb 10
\&              <select name=mv_credit_card_type>
\&          [loop
\&                  option=mv_credit_card_type
\&                  acclist=1
\&                  list=|
\&VISA=Visa,
\&MC=MasterCard,
\&SOLO=Solo,
\&DELTA=Delta,
\&MAESTRO=Maestro,
\&AMEX=Amex,
\&UKE=Electron,
\&JCB=JCB,
\&DINERS=Diners|]
\&          <option value="[loop\-code]"> [loop\-param label]
\&          [/loop]
\&          </select>
.Ve
.IP "currency" 4
.IX Item "currency"
SagePay requires that a currency code be sent, using the 3 letter \s-1ISO\s0 currency code standard,
eg, \s-1GBP\s0, \s-1EUR\s0, \s-1USD\s0. The value is taken firstly from either a page setting or a
possible value in the products database, viz 'iso_currency_code'; then falling back
to the locale setting \- for this you need to add to locale.txt:
.Sp
.Vb 2
\&    code    en_GB   en_EUR  en_US
\&    iso_currency_code   GBP EUR USD
.Ve
.Sp
It then falls back to a 'Route sagepay currency \s-1EUR\s0' type entry in catalog.cfg;
then falls back to a global variable (eg \s-1MV_PAYMENT_CURRENCY\s0 \s-1EUR\s0 Payment); and
finally defaults to \s-1GBP\s0 hard-coded into the module. This variable is returned to
the module and logged using the value returned from SagePay, rather than a value from
the page which possibly may not exist.
.IP "cvv2" 4
.IX Item "cvv2"
This is sent to SagePay as mv_credit_card_cvv2. Put this on the checkout page:
.Sp
.Vb 1
\&    <b>CVV2: &nbsp; <input type=text name=mv_credit_card_cvv2 size=6></b>
.Ve
.Sp
but note that under Card rules you must not log this value anywhere.
.IP "issue_number" 4
.IX Item "issue_number"
This is used for some debit cards, and taken from an input box on the checkout page:
.Sp
.Vb 1
\&    Card issue number: <input type=text name=mv_credit_card_issue_number value=\*(Aq\*(Aq size=6>
.Ve
.IP "mvccStartDate" 4
.IX Item "mvccStartDate"
This is used for some debit cards, and is taken from select boxes on the
checkout page in a similar style to those for the card expiry date. The labels to be
used are: 'mv_credit_card_start_month', 'mv_credit_card_start_year'. Eg:
.Sp
.Vb 10
\&                  <select name=mv_credit_card_start_year>
\&                  [loop option=start_date_year lr=1 list=\`
\&                  my $year = $Tag\->time( \*(Aq\*(Aq, { format => \*(Aq%Y\*(Aq }, \*(Aq%Y\*(Aq );
\&                  my $out = \*(Aq\*(Aq;
\&                  for ($year \- 7 .. $year) {
\&                                  /\ed\ed(\ed\ed)/;
\&                                  $last_two = $1;
\&                                  $out .= "$last_two\et$_\en";
\&                  }
\&                  return $out;
\&                  \`]
\&                  <option value="[loop\-code]"> [loop\-pos 1]
\&                  [/loop]
\&                  </select>
.Ve
.Sp
Make the select box for the start month a copy of the existing one for the expiry month, but with
the label changed and the addition of 
= \-\-select \-\-, 
as the first entry. This intentionally returns nothing for that selection and prevents the StartDate being sent.
.IP "SagePay \s-1API\s0 v2.23 extra functions ApplyAVSCV2 set to: 0 = If \s-1AVS/CV2\s0 enabled then check them.  If rules apply, use rules. (default) 1 = Force \s-1AVS/CV2\s0 checks even if not enabled for the account. If rules apply, use rules. 2 = Force \s-1NO\s0 \s-1AVS/CV2\s0 checks even if enabled on account. 3 = Force \s-1AVS/CV2\s0 checks even if not enabled for the account but \s-1DON\s0'T apply any rules. You may pass this value from the page as 'applyavscv2' to override the payment route setting. They also have Paypal integrated into this version, but I have no interest in implementing Paypal through Sagepay. There is a separate PaypalExpress module for that." 4
.IX Item "SagePay API v2.23 extra functions ApplyAVSCV2 set to: 0 = If AVS/CV2 enabled then check them.  If rules apply, use rules. (default) 1 = Force AVS/CV2 checks even if not enabled for the account. If rules apply, use rules. 2 = Force NO AVS/CV2 checks even if enabled on account. 3 = Force AVS/CV2 checks even if not enabled for the account but DON'T apply any rules. You may pass this value from the page as 'applyavscv2' to override the payment route setting. They also have Paypal integrated into this version, but I have no interest in implementing Paypal through Sagepay. There is a separate PaypalExpress module for that."
ContactFax: optional
GiftAidPayment: set to \-
	0 = This transaction is not a Gift Aid charitable donation(default)
	1 = This payment is a Gift Aid charitable donation and the customer has \s-1AGREED\s0 to donate the tax.
	You may pass this value from the page as 'giftaidpayment'
.Sp
ClientIPAddress: will show in SagePay reports, and they will attempt to Geo-locate the \s-1IP\s0.
.IP "\s-1AVSCV2\s0 SagePay do not use your rulebase or return any checks for these when using 3ds and \s-1AUTHORISE\s0. As this data is essential for many business models you should use \s-1DEFERRED\s0 instead. While thought was given to running a \s-1PAYMENT\s0 and \s-1VOID\s0 for A\*^X1 first, simply to get the \s-1AVSCV2\s0 results, this cannot be done with Maestro cards which legally must go through 3ds and so I have abandoned the idea." 4
.IX Item "AVSCV2 SagePay do not use your rulebase or return any checks for these when using 3ds and AUTHORISE. As this data is essential for many business models you should use DEFERRED instead. While thought was given to running a PAYMENT and VOID for A^X1 first, simply to get the AVSCV2 results, this cannot be done with Maestro cards which legally must go through 3ds and so I have abandoned the idea."
.PD 0
.IP "Encrypted email with card info" 4
.IX Item "Encrypted email with card info"
.PD
If you want to add the extra fields (issue no, start date) to the \s-1PGP\s0 message
emailed back to you, then set the following in catalog.cfg:
.Sp
Variable<tab>\s-1MV_CREDIT_CARD_INFO_TEMPLATE\s0 Card type: {\s-1MV_CREDIT_CARD_TYPE\s0}; Card no: {\s-1MV_CREDIT_CARD_NUMBER\s0}; Expiry: {\s-1MV_CREDIT_CARD_EXP_MONTH\s0}/{\s-1MV_CREDIT_CARD_EXP_YEAR\s0}; Issue no: {\s-1MV_CREDIT_CARD_ISSUE_NUMBER\s0}; StartDate: {\s-1MV_CREDIT_CARD_START_MONTH\s0}/{\s-1MV_CREDIT_CARD_START_YEAR\s0}
.IP "testing" 4
.IX Item "testing"
The SagePay test site is test.sagepay.com, and their live site is
live.sagepay.com. Enable one of these in \s-1MV_PAYMENT_HOST\s0 in variable.txt
(*without* any leading https://) or as 'Route sagepay host test.sagepay.com' in
catalog.cfg. Be aware that the test site is not an exact replica of the live site, and errors there
can be misleading. In particular the \*(L"SecureStatus\*(R" returned from the test site is
liable to be '\s-1NOTAUTHED\s0' when the live site will return '\s-1OK\s0'.
.IP "methods" 4
.IX Item "methods"
An \s-1AUTHENTICATE\s0 will check that the card is not stolen and contains sufficient funds.
SagePay will keep the details, so that you may settle against this a month or more
later. Against an \s-1AUTHENTICATE\s0 you may do an \s-1AUTHORISE\s0 (which settles the transaction).
.Sp
A \s-1DEFERRED\s0 will place a shadow ('block') on the funds for seven days (or so, depending
on the acquiring bank). Against a \s-1DEFERRED\s0 you may do a \s-1RELEASE\s0 to settle the transaction.
.Sp
A \s-1PAYMENT\s0 will take the funds immediately. Against a \s-1PAYMENT\s0, you may do a
\&\s-1REFUND\s0 or \s-1REPEAT\s0.
.Sp
A \s-1REPEAT\s0 may be performed against an \s-1AUTHORISE\s0 or a \s-1PAYMENT\s0. This will re-check and
take the funds in real time. You may then \s-1REPEAT\s0 a \s-1REPEAT\s0, eg for regular
subscriptions. As you need to send the amount and currency with each \s-1REPEAT\s0, you
may vary the amount of the \s-1REPEAT\s0 to suit a variation in subscription fees.
.Sp
A \s-1RELEASE\s0 is performed to settle a \s-1DEFERRED\s0. Payment of the originally specified
amount is guaranteed if the \s-1RELEASE\s0 is performed within the seven days for which
the card-holder's funds are 'blocked'.
.Sp
A \s-1REFUND\s0 may be performed against a \s-1PAYMENT\s0, \s-1RELEASE\s0, or \s-1REPEAT\s0. It may be for a
partial amount or the entire amount, and may be repeated with several partial
REFUNDs so long as the total does not exceed the original amount.
.Sp
A \s-1DIRECTREFUND\s0 sends funds from your registered bank account to the nominated credit card.
This does not need to refer to any previous transaction codes, and is useful if you need to
make a refund but the customer's card has changed or the original purchase was not made by card.
.SS "Troubleshooting"
.IX Subsection "Troubleshooting"
Try a sale with  any other test number given by SagePay, eg:
	Visa \s-1VISA\s0 4929 0000 0000 6
    Mastercard  \s-1MC\s0 5404 0000 0000 0001
    Delta \s-1DELTA\s0 4462 0000 0000 0000 0003
    Visa Electron \s-1UK\s0 Debit  	\s-1UKE\s0  	4917300000000008
    Solo \s-1SOLO\s0 6334 9000 0000 0000 0005 issue no 1
    Switch (\s-1UK\s0 Maestro) \s-1MAESTRO\s0 5641 8200 0000 0005 issue no 01.
    Maestro \s-1MAESTRO\s0 300000000000000004
	AmericanExpress \s-1AMEX\s0  	3742 0000 0000 004
.PP
You need these following values to ensure a positive response:
\&\s-1CV2:\s0 123
Billing Address: 88
Billing PostCode: 412
and the password at their test server is 'password'.
.PP
If nothing works:
.IP "\(bu" 4
Make sure you \*(L"Require\*(R"d the module in interchange.cfg:
.Sp
.Vb 1
\&    Require module Vend::Payment::SagePay
.Ve
.IP "\(bu" 4
Make sure either Net::SSLeay or Crypt::SSLeay and LWP::UserAgent are installed
and working. You can test to see whether your Perl thinks they are:
.Sp
.Vb 3
\&    perl \-MNet::SSLeay \-e \*(Aqprint "It works\en"\*(Aq
\&or
\&    perl \-MLWP::UserAgent \-MCrypt::SSLeay \-e \*(Aqprint "It works\en"\*(Aq
.Ve
.Sp
If either one prints \*(L"It works.\*(R" and returns to the prompt you should be \s-1OK\s0
(presuming they are in working order otherwise).
.IP "\(bu" 4
Check the error logs, both catalogue and global. Make sure you set your payment
parameters properly. Try an order, then put this code in a page:
.Sp
.Vb 8
\&    <XMP>
\&    [calc]
\&        my $string = $Tag\->uneval( { ref => $Session\->{payment_result} });
\&        $string =~ s/{/{\en/;
\&        $string =~ s/,/,\en/g;
\&        return $string;
\&    [/calc]
\&    </XMP>
.Ve
.Sp
That should show what happened.
.IP "\(bu" 4
If you have a \s-1PGP/GPG\s0 failure when placing an order through your catalogue
then this may cause the module to be immediately re-run. As the first run would
have been successful, meaning that both the basket and the credit card information
would have been emptied, the second run will fail. The likely error message within
the catalogue will be:
\&\*(L"Can't figure out credit card expiration\*(R". Fixing \s-1PGP/GPG\s0 will fix this error.
.Sp
If you get the same error message within the Virtual Terminal, then you haven't
set the order route as noted above.
.IP "\(bu" 4
If all else fails, Zolotek and other consultants are available to help
with integration for a fee.
.SH "AUTHORS"
.IX Header "AUTHORS"
Lyn St George <info@zolotek.net>, based on original code by Mike Heins
<mike@perusion.com> and others.
.SS "\s-1CREDITS\s0 Hillary Corney (designersilversmiths.co.uk), Jamie Neil (versado.net), Andy Mayer (andymayer.net) for testing and suggestions."
.IX Subsection "CREDITS Hillary Corney (designersilversmiths.co.uk), Jamie Neil (versado.net), Andy Mayer (andymayer.net) for testing and suggestions."