# Vend::Payment::Merchantware - Interchange Merchant Warehouse support # # This program is free software; you can redistribute it and/or modify # it under the terms of the GNU General Public License as published by # the Free Software Foundation; either version 2 of the License, or # (at your option) any later version. # # This program is distributed in the hope that it will be useful, # but WITHOUT ANY WARRANTY; without even the implied warranty of # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the # GNU General Public License for more details. # # You should have received a copy of the GNU General Public # License along with this program; if not, write to the Free # Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, # MA 02110-1301 USA. package Vend::Payment::Merchantware; =head1 NAME Vend::Payment::Merchantware - Interchange Merchant Warehouse Support =head1 SYNOPSIS &charge=merchantware or [charge mode=merchantware param1=value1 param2=value2] =head1 PREREQUISITES SOAP::Lite =head1 DESCRIPTION The Vend::Payment::Merchantware module implements the merchantware() routine for use with Interchange. It is compatible on a call level with the other Interchange payment modules -- in theory (and even usually in practice) you could switch from a different payment module to Merchantware with a few configuration file changes. To enable this module, place this directive in C: Require module Vend::Payment::Merchantware This I be in interchange.cfg or a file included from it. Make sure CreditCardAuto is off (default in Interchange demos). The mode can be named anything, but the C parameter must be set to C. To make it the default payment gateway for all credit card transactions in a specific catalog, you can set in C: Variable MV_PAYMENT_MODE merchantware It uses several of the standard settings from Interchange payment. Any time we speak of a setting, it is obtained either first from the tag/call options, then from an Interchange order Route named for the mode, then finally a default global payment variable, For example, the C parameter would be specified by: [charge mode=merchantware id=YourMerchantwareID] or Route merchantware id YourMerchantwareID or with only Merchantware as a payment provider Variable MV_PAYMENT_ID YourMerchantwareID The active settings are: =over 4 =item id Your account ID, supplied by Merchant Warehouse when you sign up. Global parameter is MV_PAYMENT_ID. =item secret Your account key (not password), provided by Merchant Warehouse when you sign up. Global parameter is MV_PAYMENT_SECRET. =item partner Your account name, selected by you or provided by Merchant Warehouse when you sign up. Global parameter is MV_PAYMENT_PARTNER. =item transaction The type of transaction to be run. Valid values are: Interchange Merchantware ---------------- ----------------- auth PreAuthorizationKeyed sale SaleKeyed credit Refund void Void settle PostAuthorization (from previous auth transaction) repeat_sale RepeatSale (from previous sale or auth transaction) void_auth VoidPreAuthorization settle_batch SettleBatch level2_sale Level2SaleKeyed Default is C. =item check_sub Name of a Sub or GlobalSub to be called after the result hash has been received. A reference to the modifiable result hash is passed into the subroutine, and it should return true (in the Perl truth sense) if its checks were successful, or false if not. The transaction type is passed in as a second arg, if needed. This can come in handy since, strangely, MerchantWare has no option to decline a charge when AVS or CSC data come back negative. If you want to fail based on a bad AVS check, make sure you're only doing an auth -- B, or your customers would get charged on orders that fail the AVS check and never get logged in your system! Add the parameters like this: Route merchantware check_sub mw_check This is a matching sample subroutine you could put in interchange.cfg: GlobalSub <{RESULT} = 99; $result->{ErrorMessage} = q{The card security code you entered does not match. Additional failed attempts may hold your available funds}; } else { $result->{RESULT} = 112; $result->{ErrorMessage} = q{The billing address you entered does not match the cardholder's billing address}; } $result->{MStatus} = 'failure'; return 0; } EOR That would work equally well as a Sub in catalog.cfg. It will succeed if either the address or zip is 'Y', or if both are unknown. If it fails, it sets the result code and error message in the result hash using Merchantware's own (otherwise unused) 112 result code, meaning C. Of course you can use this sub to do any other post-processing you want as well. =back The following should rarely be used, as the supplied defaults are usually correct. =over 4 =item remap This remaps the form variable names to the ones needed by Merchantware. See the C heading in the Interchange documentation for use. =item test Set this to C if you wish to operate in test mode. Examples: Route merchantware test TRUE or Variable MV_PAYMENT_TEST TRUE or [charge mode=merchantware test=TRUE] =back =head2 Troubleshooting Try the instructions above, then enable test mode. A test order should complete. Then move to live mode and try a sale with the card number C<4111 1111 1111 1111> and a valid future expiration date. The sale should be denied, and the reason should be in [data session payment_error]. If it doesn't work: =over 4 =item * Make sure you "Require"d the module in interchange.cfg: Require module Vend::Payment::Merchantware =item * Check the error logs, both catalog and global. =item * Make sure you set your payment parameters properly. =item * Try an order, then put this code in a page: [calc] my $string = $Tag->uneval( { ref => $Session->{payment_result} }); $string =~ s/{/{\n/; $string =~ s/,/,\n/g; return $string; [/calc] That should show what happened. =item * If all else fails, consultants are available to help with integration for a fee. You can find consultants here: https://www.interchangecommerce.org/i/dev/support/index =back =head1 TOKENS MerchantWarehouse returns a token for each transaction. This is a reference to the customer's credit card used in the original sale or auth transaction, which you can use for future transactions against that card. For example, you can run a C using the token and expiration date. =over 4 You can also send the street address and ZIP for a C, so MerchantWarehouse will run the AVS check. However, note that MW will not decline a C if the AVS doesn't match -- this handling is done via our check_sub. This is why the check_sub only fails on AVS mismatch for C transactions. Thus, if you decide to fail a C based on AVS mismatch, you will need to modify the C to C the C. =back Tokens are valid for 18 months. However, each transaction returns a new token of its own, so if you update your system to replace your original token with the one returned, you can effectively have a valid token for the life of the credit card (or until the expiration date is reached). =head1 REFERENCE =head2 Transaction Types (not all supported or available) UNKNOWN 0 This value is reserved. SALE 1 A SALE charges an amount of money to a customer's credit card. REFUND 2 A REFUND credits an amount of money to a customer's credit card. VOID 3 A VOID removes a SALE, REFUND, FORCE, POSTAUTH, or ADJUST transaction from the current credit card processing batch. FORCE 4 A FORCE forces a charge on a customer's credit card. AUTH 5 An AUTH reserves or holds an amount of money on a customer's credit card. CAPTURE 6 A CAPTURE commits a single transaction as though it were batched. This feature is unsupported. ADJUST 7 An ADJUST is an adjustment on the amount of a prior sale or capture. Usually this is employed by businesses where tip-adjust on credit transactions are allowed. REPEATSALE 8 A REPEATSALE is a repeated sale of a prior sale transaction. Most accounts and merchants do not use this transaction type. POSTAUTH 9 A POSTAUTH completes the transaction process for a prior Authorization and allows it to enter the batch. LEVELUPSALE 11 A LEVELUPSALE charges an amount of money to a customer's LevelUp account. LEVELUPCREDIT 12 A LEVELUPCREDIT credits an amount of money to a customer's LevelUp account. =head2 Response Values (Error Codes) -100 Transaction NOT Processed; Generic Host Error 0 Approved 1 User Authentication Failed 2 Invalid Transaction 3 Invalid Transaction Type 4 Invalid Amount 5 Invalid Merchant Information 7 Field Format Error 8 Not a Transaction Server 9 Invalid Parameter Stream 10 Too Many Line Items 11 Client Timeout Waiting for Response 12 Decline 13 Referral 14 Transaction Type Not Supported In This Version 19 Original Transaction ID Not Found 20 Customer Reference Number Not Found 22 Invalid ABA Number 23 Invalid Account Number 24 Invalid Expiration Date 25 Transaction Type Not Supported by Host 26 Invalid Reference Number 27 Invalid Receipt Information 28 Invalid Check Holder Name 29 Invalid Check Number 30 Check DL Verification Requires DL State 40 Transaction did not connect (to NCN because SecureNCIS is not running on the web server) 50 Insufficient Funds Available 99 General Error 100 Invalid Transaction Returned from Host 101 Timeout Value too Small or Invalid Time Out Value 102 Processor Not Available 103 Error Reading Response from Host 104 Timeout waiting for Processor Response 105 Credit Error 106 Host Not Available 107 Duplicate Suppression Timeout 108 Void Error 109 Timeout Waiting for Host Response 110 Duplicate Transaction 111 Capture Error 112 Failed AVS Check 113 Cannot Exceed Sales Cap 1000 Generic Host Error 1001 Invalid Login 1002 Insufficient Privilege or Invalid Amount 1003 Invalid Login Blocked 1004 Invalid Login Deactivated 1005 Transaction Type Not Allowed 1006 Unsupported Processor 1007 Invalid Request Message 1008 Invalid Version 1010 Payment Type Not Supported 1011 Error Starting Transaction 1012 Error Finishing Transaction 1013 Error Checking Duplicate 1014 No Records To Settle (in the current batch) 1015 No Records To Process (in the current batch) =head2 AVS Response Codes X Exact: Address and nine-digit Zip match Y Yes: Address and five-digit Zip match A Address: Address matches, Zip does not Z 5-digit Zip: 5-digit Zip matches, address doesn't W Whole Zip: 9-digit Zip matches, address doesn't N No: Neither address nor Zip matches U Unavailable: Address information not available G Unavailable: Address information not available for international transaction R Retry: System unavailable or time-out E Error: Transaction unintelligible for AVS or edit error found in the message that prevents AVS from being performed S Not Supported: Issuer doesn't support AVS service B * Street Match: Street addresses match for international transaction, but postal code doesn't C * Street Address: Street addresses and postal code not verified for international transaction D * Match: Street addresses and postal codes match for international transaction I * Not Verified: Address Information not verified for International transaction M * Match: Street addresses and postal codes match for international transaction P * Postal Match: Postal codes match for international transaction, but street address doesn't 0 ** No response sent 5 Invalid AVS response * These values are Visa specific. ** These values are returned by the Payment Server and not the processor. =head2 CVV Response Codes M CVV2/CVC2/CID Match N CVV2/CVC2/CID No Match P Not Processed S Issuer indicates that the CV data should be present on the card, but the merchant has indicated that the CV data is not present on the card. U Unknown / Issuer has not certified for CV or issuer has not provided Visa/MasterCard with the CV encryption keys. X Server Provider did not respond =head1 NOTE There is actually nothing in the package Vend::Payment::Merchantware. It changes packages to Vend::Payment and places things there. =head1 AUTHORS Josh Lavin =cut BEGIN { eval { package Vend::Payment; require SOAP::Lite; }; if ($@) { die "Required modules for Merchantware NOT found. $@\n"; } ::logGlobal("%s payment module loaded",__PACKAGE__) unless $Vend::Quiet or ! $Global::VendRoot or ! $Global::VendRoot; } package Vend::Payment; sub merchantware { my ($user, $amount) = @_; my ($opt, $secret, $partner); if (ref $user) { $opt = $user; $user = $opt->{id} || undef; $secret = $opt->{secret} || undef; $partner = $opt->{partner} || undef; } else { $opt = {}; } my $actual; if ($opt->{actual}) { $actual = $opt->{actual}; } else { my (%actual) = map_actual(); $actual = \%actual; } #::logDebug("actual map result: " . ::uneval($actual)); if (! $user) { $user = charge_param('id') or return ( MStatus => 'failure-hard', MErrMsg => errmsg('No account id'), ); } if (! $secret) { $secret = charge_param('secret') or return ( MStatus => 'failure-hard', MErrMsg => errmsg('No account password'), ); } if (! $partner) { $partner = charge_param('partner') or return ( MStatus => 'failure-hard', MErrMsg => errmsg('No account partner'), ); } my @override = qw/ order_id auth_code mv_credit_card_exp_month mv_credit_card_exp_year mv_credit_card_number /; for(@override) { next unless defined $opt->{$_}; $actual->{$_} = $opt->{$_}; } my $exp = sprintf( '%02d%02d', $actual->{mv_credit_card_exp_month}, $actual->{mv_credit_card_exp_year}, ); my $transtype = $opt->{transaction} || charge_param('transaction') || 'sale'; my %type_map = (qw/ authorize auth settle_prior settle refund credit return credit reverse void /); if (defined $type_map{$transtype}) { $transtype = $type_map{$transtype}; } my $order_id = gen_order_id($opt); my $precision = $opt->{precision} || charge_param('precision') || 2; $amount = $opt->{total_cost} if ! $amount; if (! $amount) { $amount = Vend::Interpolate::total_cost(); $amount = Vend::Util::round_to_frac_digits($amount, $precision); } my $salestax = $opt->{salestax} || ''; if (! $salestax) { $salestax = Vend::Interpolate::salestax(); $salestax = Vend::Util::round_to_frac_digits($salestax, $precision); } if ($transtype eq 'void' and $order_id =~ /\w+$/) { $transtype = 'void_auth'; } #::logDebug("merchantware: transtype=$transtype, amount=$amount"); # common query params: my %query = ( merchantName => $partner, merchantSiteId => $user, merchantKey => $secret, invoiceNumber => $actual->{mv_order_number} || $actual->{mv_transaction_id}, registerNumber => $Vend::Session->{ohost}, merchantTransactionID => $order_id, ); ## could also set forceDuplicate to 'true' (must be a string of 'true', apparently) my ($method, $token); if ( $actual->{auth_code} ) { $actual->{auth_code} =~ s/,(\w+)// and $token = $1; } if ( $transtype =~ /^(?:sale|auth|level2_sale)/ ) { my %addl = ( amount => $amount, cardNumber => $actual->{mv_credit_card_number}, expirationDate => $exp, cardholder => $actual->{b_name}, avsStreetAddress => $actual->{b_address}, avsStreetZipCode => $actual->{b_zip}, cardSecurityCode => $actual->{mv_credit_card_cvv2}, ); while (my ($k,$v) = each %addl) { $query{$k} = $v; } $method = ($transtype eq 'sale') ? 'SaleKeyed' : 'PreAuthorizationKeyed'; } elsif ($transtype eq 'credit') { $query{token} = $token || $actual->{auth_code}; $query{overrideAmount} = $amount; $method = 'Refund'; } elsif ($transtype eq 'void') { $query{token} = $token || $actual->{auth_code}; $method = 'Void'; } elsif ($transtype eq 'settle') { $query{token} = $token || $actual->{auth_code}; $query{amount} = $amount; $method = 'PostAuthorization'; } elsif ($transtype eq 'repeat_sale') { my %addl = ( token => $token || $actual->{auth_code}, overrideAmount => $amount, expirationDate => $exp, avsStreetAddress => $actual->{b_address}, avsStreetZipCode => $actual->{b_zip}, ); while (my ($k,$v) = each %addl) { $query{$k} = $v; } $method = 'RepeatSale'; } elsif ($transtype eq 'void_auth') { $query{token} = $token || $actual->{auth_code}; $method = 'VoidPreAuthorization'; } elsif ($transtype eq 'settle_batch') { $method = 'SettleBatch'; } if ($transtype eq 'level2_sale') { $query{customerCode} = $Vend::Session->{username} || $Vend::Session->{id}; $query{poNumber} = $actual->{po_number}; $query{taxAmount} = $salestax; $method = 'Level2SaleKeyed'; } # Uncomment all the following block to use the debug statement. It strips # the arg of any sensitive credit card information and is safe # to enable in production. #{ # my %munged_query = %query; # $munged_query{merchantKey} = 'XXXXXX'; # $munged_query{cardNumber} =~ s/^(\d{4})(.*)/$1 . ('X' x length($2))/e; # $munged_query{cardSecurityCode} =~ s/./X/g; #::logDebug("merchantware: method=$method"); #::logDebug("merchantware query: " . ::uneval(\%munged_query)); #} ## Request. my $host = charge_param('test') ? 'staging.merchantware.net' : 'ps1.merchantware.net'; my @parms; while (my ($k,$v) = each %query) { push @parms, SOAP::Data->name($k => $v); } my $soap = SOAP::Lite->new( proxy => "https://$host/Merchantware/ws/RetailTransaction/v4/Credit.asmx" ); # default timeout is 180 secs, from LWP::UserAgent $soap->default_ns('http://schemas.merchantwarehouse.com/merchantware/40/Credit/'); $soap->on_action( sub { join '', @_ } ); # make it ok for .NET my $reply = $soap->call($method, @parms); #::logDebug("merchantware result: $reply"); #::logDebug("merchantware: ". uneval($reply) ); my $result; if ( $reply->fault ) { return ( RESULT => -1, RESPMSG => 'System Error', MStatus => 'failure-hard', MErrMsg => 'System Error', ); } else { $result = $reply->valueof('Body/' . $method . 'Response/' . $method . 'Result' ); } #::logDebug("merchantware result: ". uneval($result) ); my ($decline, $error_detail); if ( $result->{ApprovalStatus} eq 'APPROVED' and my $check_sub_name = $opt->{check_sub} || charge_param('check_sub') ) { my $check_sub = $Vend::Cfg->{Sub}{$check_sub_name} || $Global::GlobalSub->{$check_sub_name}; if ( ref $check_sub eq 'CODE' ) { $decline = ! $check_sub->( $result, $transtype ); #::logDebug("merchantware check_sub: $check_sub_name, decline=$decline"); } else { logError("merchantware: non-existent check_sub routine %s.", $check_sub_name); } } elsif ( $result->{ApprovalStatus} ne 'APPROVED' ) { $decline = 1; $error_detail = $result->{ApprovalStatus}; $error_detail =~ s/\w+;//; } if ($decline) { $result->{MStatus} = 'failure'; my $msg = $opt->{message_declined} || errmsg( "Charge error: %s. Please call in your order or try again.", $result->{ErrorMessage} || $error_detail || 'unknown error', ); $result->{MErrMsg} = $msg; } else { $result->{MStatus} = 'success'; $result->{InvoiceNumber} ||= $order_id; } # IC names are on the left, Merchantware on the right my %result_map = ( qw/ pop.status ApprovalStatus pop.error-message ErrorMessage order-id InvoiceNumber pop.order-id InvoiceNumber pop.auth-code AuthorizationCode pop.avs_code AvsResponse pop.cvv2_resp_code CvResponse / ); for (keys %result_map) { $result->{$_} = $result->{$result_map{$_}} if defined $result->{$result_map{$_}}; } $result->{'pop.auth-code'} .= ',' . $result->{Token}; # append token to auth-code. Is split out above for voids/captures/etc, as MW uses token, not auth-code. #::logDebug('merchantware result: ' . ::uneval($result) ); return %$result; } package Vend::Payment::Merchantware; 1;