.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.29) .\" .\" 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" '' . ds C` . ds C' '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. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{ . if \nF \{ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Vend::Payment::Protx2 3pm" .TH Vend::Payment::Protx2 3pm "2016-08-31" "perl v5.22.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 "NAME" Interchange Protx Direct payment system interface .SH "PREREQUISITES" .IX Header "PREREQUISITES" Net::SSLeay or LWP::UserAgent and Crypt::SSLeay .PP wget \- a recent version built with \s-1SSL\s0 and supporting the 'connect' timeout function. .SH "QUICK START SUMMARY" .IX Header "QUICK START SUMMARY" 1. Call this module in interchange.cfg with: .PP .Vb 1 \& Require module Vend::Payment::Protx2 .Ve .PP 2. Add into products/variable.txt (tab separated): .PP .Vb 1 \& MV_PAYMENT_MODE protx .Ve .PP 3. Add a new route into catalog.cfg (options for the last entry in parentheses): .PP .Vb 10 \& Route protx id YourProtxID \& Route protx host ukvps.protx.com (ukvpstest.protx.com) \& Route protx currency GBP (USD, EUR, others, defaults to GBP) \& Route protx txtype PAYMENT (AUTHENTICATE, DEFERRED) \& Route protx available yes (no, empty) \& Route protx logzero yes (no, empty) \& Route protx double_pay yes (no, empty) \& Route protx logdir "path/to/log/dir" \& Route protx protxlog yes (no, empty) \& Route protx applyavscv2 \*(Aq0\*(Aq: if enabled then check, and if rules apply use. \& \*(Aq1\*(Aq: force checks even if not enabled; if rules apply use. \& \*(Aq2\*(Aq: force NO checks even if enabled on account. \& \*(Aq3\*(Aq: force checks even if not enabled; do NOT apply rules. \& Route protx giftaidpayment 0 (1 to donate tax to Gift Aid) .Ve .PP or put these vars into products/variable.txt instead: .PP .Vb 4 \& MV_PAYMENT_ID YourProtxID Payment \& MV_PAYMENT_MODE protx Payment \& MV_PAYMENT_HOST ukvps.protx.com Payment \& MV_PAYMENT_CURRENCY GBP Payment .Ve .PP and the rest as above. .PP 4. Create a new locale setting for en_UK as noted in \*(L"item currency\*(R" below, and copy the public space interchange/en_US/ directory to a new interchange/en_UK/ 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-1UK\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 optionally 'mv_credit_card_cvv2'. .SH "DESCRIPTION" .IX Header "DESCRIPTION" The Vend::Payment::Protx module implements the \fIProtx()\fR routine for use with Interchange. It is not compatible on a call level with the other Interchange payment modules \- Protx does things rather differently. We need to save four of the returned codes for re-use when doing a \s-1RELEASE, REPEAT,\s0 or \s-1REFUND.\s0 .PP To enable this module, place this directive in \f(CW\*(C`interchange.cfg\*(C'\fR: .PP .Vb 1 \& Require module Vend::Payment::Protx2 .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). .PP Note that the Protx '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. .PP Note also that Maestro cards can only be taken by the 3DSecure version of this module, not by this version, as Mastercard have decreed that Maestro cards will no longer be accepted without 3DSecure. .PP While \s-1PREAUTH\s0 is still in this module, it is scheduled to be dropped on the 1st August 2007 or shortly thereafter, and is only here as a backup during the changeover to \s-1AUTHENTICATE.\s0 .SS "The active settings" .IX Subsection "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`protx\*(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 1 \& Variable MV_PAYMENT_MODE protx .Ve .Sp or in variable.txt: .Sp .Vb 1 \& MV_PAYMENT_MODE protx (tab separated) .Ve .Sp if you want this to cooperate with other payment systems, eg PaypalExpress or GoogleCheckout, then see the documentation that comes with that system \- it should be fully explained there (essentially, you don't run the charge route from profiles.order but from log_transaction). .IP "id" 4 .IX Item "id" Your Protx vendor \s-1ID,\s0 supplied by Protx when you sign up. Various ways to state this: .Sp in variable.txt: .Sp .Vb 1 \& MV_PAYMENT_ID YourProtxID Payment .Ve .Sp or in catalog.cfg either of: .Sp .Vb 2 \& Route protx id YourProtxID \& Variable MV_PAYMENT_ID YourProtxID .Ve .IP "txtype" 4 .IX Item "txtype" The transaction type is one of: \s-1PAYMENT, AUTHENTICATE\s0 or \s-1DEFERRED\s0 for an initial purchase through the catalogue, and then can be one of: \s-1REFUND, RELEASE, REPEAT\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-1AUTHENTICATE\s0' entry in catalog.cfg; then falling back to a global variable in variable.txt, eg '\s-1MV_PAYMENT_TXTYPE AUTHENTICATE\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 Protx, 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 Protx server, you cannot use their terminal to process it. You must use the \s-1PTIPM\s0 which includes a function for this purpose; ie, it updates the existing order number with the new payment information returned from Protx. Note further that if you have Protx set up to require the \s-1CV2\s0 value, then the \s-1PTIPM\s0 will 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. .IP "logempty" 4 .IX Item "logempty" If 'yes, then if the response from Protx is read as empty (ie, zero bytes) the result is forced to \&'success' and the transaction logged as though the customer has paid. There are two markers set to warn of this: .Sp \&\f(CW$Session\fR\->{payment_result}{TxType} will be \s-1NULL,\s0 .Sp \&\f(CW$Session\fR\->{payment_result}{StatusDetail} will be: '\s-1UNKNOWN\s0 status \- check with Protx before dispatching goods' .Sp and you should include these into the report emailed to you. .IP "card_type" 4 .IX Item "card_type" Protx requires that the card type be sent. Valid types are: \s-1VISA, MC, AMEX, DELTA, SOLO, UKE, JCB, DINERS \s0(\s-1UKE\s0 is Visa Electron issued in the \s-1UK\s0). \s-1MAESTRO\s0 is no longer accepted without 3DSecure. This may optionally be determined by the module using regexes, or you may use a select box on the page. If there is an error in the regex match in this module due to a change in card ranges or some other fault, then Protx will refuse the transaction and return an error message to the page. Using a select box on the page automatically overrides use of the internal option. In the interests of robust reliability it is *strongly* recommended that you use a select box. .Sp You may display a select box on the checkout page like so: .Sp .Vb 10 \& .Ve .IP "currency" 4 .IX Item "currency" Protx requires that a currency code be sent, using the 3 letter \s-1ISO\s0 standard, eg, \s-1GBP, EUR, USD.\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_UK en_EUR en_US \& iso_currency_code GBP EUR USD .Ve .Sp It then falls back to a 'Route protx currency \s-1EUR\s0' type entry in catalog.cfg; then falls back to a global variable (eg \s-1MV_PAYMENT_CURRENCY EUR\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 Protx, rather than a value from the page which possibly may not exist. .IP "cvv2" 4 .IX Item "cvv2" This is sent to Protx as mv_credit_card_cvv2. Put this on the checkout page: .Sp .Vb 1 \& CVV2: .Ve .Sp but note that under \s-1PCI\s0 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: .Ve .IP "StartDate" 4 .IX Item "StartDate" 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 \& .Ve .IP "Log directory" 4 .IX Item "Log directory" To choose the directory used for logging both the Protx latency log and the double payment safeguard record, set in catalog.cfg: .Sp .Vb 1 \& Route protx logdir "path/to/log/dir" .Ve .Sp It must be relative to the catalog root directory if you have NoAbsolute set for this catalog in interchange.cfg. .Sp If logdir is not set, it defaults to the system /tmp. .Sp A somewhat dangerous option allows the payment page to specify the logdir in a form variable, like this: .Sp .Vb 1 \& .Ve .Sp This allows an individual user to have his own logs in a shared hosting environment. However, it also allows a creative end-user to create arbitrary empty files or update timestamps of existing files. .Sp Because of the potential for abuse, this option is not allowed unless you set a special route variable indicating you want it: .Sp .Vb 1 \& Route protx logdir_from_user_allowed 1 .Ve .IP "Protx \s-1API\s0 v2.22 extra functions" 4 .IX Item "Protx API v2.22 extra functions" ApplyAVSCV2 set to: .Sp .Vb 5 \& 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\*(AqT apply any rules. \& You may pass this value from the page as \*(Aqapplyavscv2\*(Aq to override the payment route setting. .Ve .Sp CustomerName: optional, may be different to the cardholder name .Sp ContactFax: optional .Sp 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 Protx reports, and they will attempt to Geo-locate the \s-1IP.\s0 .IP "Encrypted email with card info" 4 .IX Item "Encrypted email with card info" 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 .Vb 1 \& VariableMV_CREDIT_CARD_INFO_TEMPLATE Card type: {MV_CREDIT_CARD_TYPE}; Card no: {MV_CREDIT_CARD_NUMBER}; Expiry: {MV_CREDIT_CARD_EXP_MONTH}/{MV_CREDIT_CARD_EXP_YEAR}; Issue no: {MV_CREDIT_CARD_ISSUE_NUMBER}; StartDate: {MV_CREDIT_CARD_START_MONTH}/{MV_CREDIT_CARD_START_YEAR} .Ve .IP "testing" 4 .IX Item "testing" The Protx test site is ukvpstest.protx.com, and their live site is ukvps.protx.com. Enable one of these in \s-1MV_PAYMENT_HOST\s0 in variable.txt (*without* any leading https://) or as 'Route protx host ukvpstest.protx.com' in catalog.cfg. .IP "methods" 4 .IX Item "methods" \&\s-1NB:\s0 Protx have removed \s-1PREAUTH\s0 from their protocol and replaced it with \s-1AUTHENTICATE/AUTHORISE.\s0 .Sp An \s-1AUTHENTICATE\s0 will validate the card and store the card details on Protx's system for up to 90 days. Against this you may \s-1AUTHORISE\s0 for any amount up to 115% of the original value. .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-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, RELEASE, AUTHORISE\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 "Virtual Payment Terminal" .IX Subsection "Virtual Payment Terminal" This has now been split out from this module, and may be found as the rather pretentiously named Payment Terminal Interchange Plug-in Module (\s-1PTIPM\s0), also on http://kiwi.zolotek.net. The \s-1PTIPM\s0 does refunds and repeats, directrefunds, and converts offline transactions to online ones. Being a plugin to the Interchange Admin Panel it integrates these operations into your database. .SH "TROUBLESHOOTING" .IX Header "TROUBLESHOOTING" Only the test card numbers given below will be successfully authorised (all other card numbers will be declined). .PP .Vb 9 \& VISA 4929 0000 0000 6 \& MASTERCARD 5404 0000 0000 0001 \& DELTA 4462000000000003 \& SOLO 6334900000000005 issue 1 \& DOMESTIC MAESTRO 5641 8200 0000 0005 issue 01 (should be rejected now) \& AMEX 3742 0000 0000 004 \& ELECTRON 4917 3000 0000 0008 \& JCB 3569 9900 0000 0009 \& DINERS 3600 0000 0000 08 .Ve .PP You'll also need to supply the following values for \s-1CV2,\s0 Billing Address Numbers and Billing Post Code Numbers. These are the only values which will return as Matched on the test server. Any other values will return a Not Matched on the test server. .PP .Vb 3 \& CV2 123 \& Billing Address Numbers 88 \& Billing Post Code Numbers 412 .Ve .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::Protx2 .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 \& 
\&    [calcn]
\&        my $string = $Tag\->uneval( { ref => $Session\->{payment_result} });
\&        $string =~ s/{/{\en/;
\&        $string =~ s/,/,\en/g;
\&        return $string;
\&    [/calcn]
\&
.Ve .Sp That should show what happened. .IP "\(bu" 4 If you have unexplained and unlogged errors then check you have allowed the new database fields to be \s-1NULL.\s0 If MySQL tries to write to a field that is marked \s-1NOT NULL\s0 then it will fail silently. .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 "RESOURCES" .IX Header "RESOURCES" http://kiwi.zolotek.net is the home page with the latest version. Also to be found on Kevin Walsh's excellent Interchange site, http://interchange.rtfm.info. .SH "AUTHORS" .IX Header "AUTHORS" Lyn St George , based on original code by Mike Heins and others. .SH "CREDITS" .IX Header "CREDITS" Hillary Corney (designersilversmiths.co.uk), Jamie Neil (versado.net), Andy Mayer (andymayer.net) for testing and suggestions. .SH "LICENSE" .IX Header "LICENSE" GPLv2