Provided by: interchange_5.7.7-2_amd64 bug

Interchange CyberSource Support

       Vend::Payment::CyberSource Revision: 1.0

SYNOPSIS

           &charge=cybersource

               or

           [charge gateway=cybersource param1=value1 param2=value2]

              or, with a route named foo with gateway => cybersource

           [charge route=foo]

       While you have free will, please use a route. See below.

PREREQUISITES

        SOAP::Lite
        XML::Pastor::Schema::Parser
        LWP::Simple
        OpenSSL

DESCRIPTION

       The Vend::Payment::CyberSource module implements the cybersource() routine for use with
       Interchange. It is compatible on a call level with the other Interchange payment modules.

       To enable this module, place this directive in "interchange.cfg":

           Require module Vend::Payment::CyberSource

       This must be in interchange.cfg or a file included from it.

       Make sure CreditCardAuto is off (default in Interchange demos).

       This module supersedes Vend::Payment::ICS. With only minor adjustments to the payment
       route and some changes to the keys in $Session->{payment_result},
       Vend::Payment::CyberSource should function as a drop-in replacement for
       Vend::Payment::ICS. If you have legacy support for the SCMP API and don't need any of the
       new features supported in this module, you do not need to change.  However, all new
       CyberSource clients will have to use this module as they do not allow new clients to use
       SCMP.

       If you do choose to replace the current use of Vend::Payment::ICS, you will have to
       abandon the merchant keys generated by ecert() (I know, it's a devastating blow) and
       instead generate a transaction key from within the online merchant account. That new
       transaction key will be added to your payment route.

       Whenever possible, please set your payment parameters using a payment route or passed as
       arguments to [charge] directly. No special effort has been made to consistently fall back
       on the charge_param() function, which plucks values out of the MV_PAYMENT_* variable
       space. It is not possible to isolate variables to a specific charge routine using
       charge_param() and, as such, it should be viewed with suspicion, rather than being used as
       a crutch. In particular, this module makes the assumption that certain critical route
       parameters will be present in $opt, and the best way to ensure they are in there is to use
       a payment route.

   Simple made Simple
       You may treat this gateway module as though it were the Simple API. The construction of
       the requests and responses within the Vend::Payment namespace will correspond either
       virtually (in the case of SOAP errors, it's probably different) or exactly (in the case of
       successful requests, even if the transaction itself is not successful) to the
       request/response name/value pairs documented for the Simple API.

       Unlike its name may imply, the Simple API is in fact not simple to install.  Difficult
       becomes Impossible if you have a 64-bit OS. CyberSource as of this module's writing has
       not seen fit to port either of their client APIs (SCMP or Simple) to a 64-bit version.
       However, because this is actually the SOAP clientless toolkit wrapped to impersonate
       Simple, you get to by-pass the pain you'd otherwise have to feel to install Simple into
       your environment.

       What this means: do NOT install the Simple API! It will likely be a big pain and it is
       useless for the purposes of this module. You only need to ensure the modules/software
       indicated in PREREQUISITES are installed.

       You can find the documentation for the Simple API at the following URL:

       http://apps.cybersource.com/library/documentation/sbc/api_guide/html/

       Again, do NOT install the Simple API; just use the docs as though it is already installed.

   Options
       merchant_id
           ID obtained from CyberSource. Likely the same value you use to log in to the online
           merchant interface for your account.

       transaction_key
           Key generated from the CyberSource online merchant interface.

       api_version
           Which version of Simple to use. When setting up, just pick the current one, and
           updates are likely unneeded unless new features come out that you need.

           You can see the full list of versions, and what features they each support (if you
           like reading XSD) here:

           https://ics2ws.ic3.com/commerce/1.x/transactionProcessor/

           The opt should be just the number, something like 1.44

       live
           Calls go to production environment when value is 'true' (as in, the string true, and
           not just perly true, to give those already familiar with the actual Simple API warm
           fuzzy feelings). Any other value (or no value) is assumed to go to the test
           environment.

       xsd_cache_dir
           Directory relative to catroot for caching the XSD files for each API version and from
           each environment (live or test). If not set, no caching will occur, but this is not
           recommended.

           The module makes an initial request to CyberSource to get the XSD for whatever version
           of the API you're using, so that it knows what request values to look for and are
           valid.  Ideally, you don't want every single request repeating this process.

           If this option is set, the module will first look for the appropriate XSD associated
           with the correct version and environment in the cache dir. If it's not found, only
           then will it request the XSD from CyberSource. Once it's obtained from from
           CyberSource, it will cache it in the same location it initially looked, so all
           subsequent requests using the same API version in the same environment can use the
           cached XSD instead.

           There should be no reason to expire the cache, but if you wish to you'll have to do so
           manually. There's no built-in expiration mechanism. Because a published API will be
           static, the only reason you would need to expire the cached version is if it somehow
           became corrupted.

           Also, don't manually replace files in the cache. The XSD retrieved from CyberSource
           must be slightly tweaked to work with the XSD parsing module. That tweak is frozen
           into the cache. If you wish to refresh the cache, just remove the cache files and let
           the module itself pull down the correct version and cache it for you.

       acct_type
           The type of the account for the customer's payment instrument. Currently supported:

               * cc (standard credit card, the default)
               * bml (Bill Me Later)
               * pp (Paypal Express Checkout)
               * ec (Electronic Check)

       transaction
           Type of transaction to run.

           acct_type cc or bml:

               * auth (or authorize, A)
               * settle (or capture, D)
               * sale (or S) - auth and settle in same request
               * credit (or C)
               * auth_reversal (or R) (not widely supported; use with caution)
               * void (or V)

           For additional information on acct_type 'bml' transactions, see full Bill Me Later
           section below.

           acct_type pp:

               * pp_set (Exp. checkout set service)
               * pp_get (Exp. checkout get service)
               * pp_dopmt (Exp. Checkout do payment)
               * pp_ord_setup (Exp. Checkout order setup)
               * pp_auth (auth service)
               * pp_bill (capture service)
               * pp_sale (auth and capture together)
               * pp_authrev (reverse auth)
               * pp_refund (refund service)

           See Paypal section below for full details

           acct_type ec:

               * ec_debit
               * ec_credit

           See Electronic Check section below for full details

       origid
           Original transaction ID referenced for follow-on transactions. E.g., the requestID of
           an auth that is to be captured.

       order_id or order_number
           Passed over as merchantReferenceCode with request. Also very likely needed for any use
           of items_sub (see below).

       apps
           The list of allowable applications, space- or comma-separated, for this request. Added
           as a security measure to restrict use on any applications that aren't needed and might
           be a risk (such as credits if they'll never be issued through Interchange). All ics_*
           apps apply to cc and bml account types. pp_* and ec_* apply to account types pp and
           ec, respectively:

               * ics_auth (needed for auth, sale)
               * ics_auth_reversal (needed for auth_reversal)
               * ics_bill (needed for settle, sale)
               * ics_credit (needed for credit)
               * ics_void (needed for void)
               * pp_ec_set (needed for pp_set)
               * pp_ec_get (needed for pp_get)
               * pp_ec_dopmt (needed for pp_dopmt, pp_sale)
               * pp_ec_ord_setup (needed for pp_ord_setup)
               * pp_auth (needed for pp_auth)
               * pp_capture (needed for pp_bill, pp_sale)
               * pp_authrev (needed for pp_authrev)
               * pp_refund (needed for pp_refund)
               * ec_debit (needed for ec_debit)
               * ec_credit (needed for ec_credit)

           It is recommended to exclude any apps you will not use from the list.

       ship_map
           List of mv_shipmode values to map to the various allowable values in
           shipTo_shippingMethod. List is optional and defaults to 'lowcost'.

           The list should be in a form that is appropriate for perl's qw() to put the list into
           a hash. E.g.,:

               GNDRES  lowcost
               2DAY    twoday
               ...

           List of possible CyberSource values:

               * sameday
               * oneday
               * twoday
               * threeday
               * lowcost
               * pickup
               * other
               * none

       mv_credit_card_number
           Unlike many (if not the rest) of the gateway modules, you can pass in the card number
           as an option. However, the code prefers the value from the traditional source from
           $CGI via the actual opt. This option will mostly be unneeded.

       any Simple request keys
           The code will take any of the Simple key names directly through $opt.  However, it
           will prefer any defined values associated with actual() over $opt, which may not be
           what you expect.

       items_sub
           Custom subroutine that can be used to construct the order sent over to CyberSource. By
           default, module uses $Vend::Items. Routine will be essential for any processing of
           payments that are not directly associated with the immediate session. E.g., any
           payment interface developed for the admin to process transactions after the order
           already exists.

           Routine should return an array that matches the basics of an Interchange cart.  Most
           likely use would be to construct a cart out of an order already in the database, but
           as long as the routine returns a cart-style array, it doesn't matter how it's
           constructed.

           Each line item needs the following attributes:

               * code
               * quantity

           To determine cost, each line-item hash is passed to Vend::Data::item_price().  So, if
           your pricing demands more line-item attributes to calculate correctly, you'll need to
           ensure they are present.

           Routine can be either a catalog or global sub, with the code preferring the catalog
           sub. Args:

               * Reference to copy of request hash
               * $opt

       check_sub
           Post-reply routine that can be used to alter the status and/or response hash returned
           from cybersource(). Examples of usage:

           ·   Auth succeeds, but we want it treat as a failure because of AVS response.

           ·   Auth fails, but error is a communication failure, so we want to treat it as
               success and follow up manually with customer to resolve.

           ·   Decision Manager result raises concerns, so we add a response parameter that
               indicates the order should not be fulfilled automatically, but rather funnel to a
               queue for manual review.

           Routine should return 'success' or 'failed' if it is to be authoritative as to that
           determination. Otherwise, it should return undef and let the code calculate 'success'
           or 'failed' based on the value of the 'decision' key in the response hash.

           It can be either a catalog or global sub, with the code preferring the catalog sub.
           Args:

               * Reference to response hash (so it can be modified directly)
               * Reference to a copy of the request hash
               * $opt

       ip_address
           IP to supply to CyberSource for the transaction. Optional and defaults to
           $Session->{shost} if defined, or $Session->{ohost} otherwise.

       shipping
           Amount to supply CyberSource for shipping costs. Defaults to [shipping].

       amount
           Amount to supply to CyberSource to apply to the transaction.

           Note that this value supersedes all the costs provided along with the order and
           shipping amounts. They do not have to agree. Supplying amount means CyberSource will
           use that specific amount. If amount is not supplied, I believe that CyberSource will
           construct a transaction amount from the sum of the order and shipping, but I do not
           recommend this.

           By default, amount will be derived from [total-cost].

       timeout
           Number of seconds for a request without a response before the process is killed.

       merrmsg, merrmsg_bml
           Override the default error messages presented to users in the event of a failed
           transaction attempt, for acct_type cc and bml, respectively. merrmsg will run through
           sprintf() and can have the reason code and reason message, in that order, embedded in
           message with the use of %s as a placeholder. merrmsg_bml has no such provision because
           the errors that come back from Paymentech for BML failures range between cryptic and
           useless.

       The following options are valid for Paypal usage only:

       returnurl
           URL to which the customer's browser is returned after choosing to pay with PayPal.

       cancelurl
           URL to which customers are returned if they do not approve the use of PayPal for
           payment.

       maxamount
           Expected maximum total amount of the entire order, including shipping costs and tax
           charges.

       billinginfo
           Optional boolean indicator to request that PayPal return the user's billing
           information on GetRequest.

           0 (default): Do not return the customer's billing address.

           1: Return the customer's billing address.

       useraction
           Which PayPal useraction is desired. This essentially indicates the label of the button
           for the user when coming back from PayPal to the merchant's site.  Options are:

           continue
               Default. Standard usage when merchants expect the user to come back to their site
               and provide more data, or explicit actions, to complete checkout. Button user
               clicks is labeled "Continue".

           commit
               Usage option when merchant does not require to collect more data or have the user
               perform any actions on the merchant site before completing the order. The API
               behavior is the same as that for usertype continue; the only difference is the
               button the user is to click will say "Buy Now".

           Regardless of which useraction is specified, the merchant's site must process a
           getrequest and dopayment in response in order to complete the sale.  Clicking "Buy
           Now" doesn't actually do any such thing on PayPal's side. It just authorizes the
           merchant to immediately process payment once the user has returned.

       order_desc
           Description of items the customer is purchasing.

       confirmshipping
           Flag that indicates if you require the customer's shipping address on file with PayPal
           to be a confirmed address. 0 (default) not confirmed, 1 confirmed.

       noshipping
           Flag that indicates if the shipping address should be displayed on the PayPal Web
           pages. 0 (default) show shipping, 1 suppress shipping display.

       addressoverride
           Customer-supplied address sent in the SetExpressCheckout request rather than the
           address on file with PayPal for this customer.

           You can use this field only with the payment method, not with the shortcut method. See
           Overview of PayPal Express Checkout for a description of the PayPal methods.

           Possible values:

           0 (default): Display the address on file with PayPal. The customer cannot edit this
           address.

           1: Display the customer-supplied address. The customer can edit this in PayPal Express
           Checkout.

       locale
           Locale of pages displayed by PayPal during Express Checkout.

       headerbackcolor
           Background color for the header of the payment page. Format: HTML Hexadecimal color.

       headerbordercolor
           Border color around the header of the payment page. Format: HTML Hexadecimal color.

       headerimg
           URL for the image that will be displayed in the upper left area of the payment page.

       payflowcolor
           Background color for the payment page. Format: HTML Hexadecimal color.

       pp_token
           Timestamped token by which you identify to PayPal that you are processing this payment
           with Express Checkout. Corresponds with paypalToken description in CyberSource docs.
           Normally not needed as module will handle internally for most typical scenarios.

       pp_payer_id
           Unique PayPal customer account identification number that was returned in the
           payPalEcGetDetailsService reply message. Corresponds with paypalPayerId description in
           CyberSource docs. Normally not needed as module will handle internally for most
           typical scenarios.

       return_ec_set
           Boolean to indicate that an EC set call is to be issued as a return call; that is, a
           call to amend the user's Paypal data returned in a subsequent EC get call on the same
           session established by an initial EC set call.

           The same can be accomplished by calling EC set while explicitly supplying the paypal
           token and CyberSource request ID and token of the original call to EC set establishing
           that session.

       transaction_id
           For use in captures, refunds, and auth reversals. Maps to the paypal-specific
           transaction ID of the original request, and not the RequestID, which is the
           CyberSource transaction ID.

           Specifically, it should relate in the following manner:
               Maps to Service Param                               Obtained From
               payPalDoCaptureService_paypalAuthorizationId
           payPalEcDoPaymentReply_transactionId
               payPalAuthReversalService_paypalAuthorizationId
           payPalAuthorizationReply_transactionId
               payPalRefundService_paypalCaptureId
           payPalDoCaptureReply_transactionId

   Bill Me Later
       This module provides full support for Bill Me Later (BML) transactions. Some important
       notes on using BML with this module:

       See CyberSource's full BML documentation for details:

       http://apps.cybersource.com/library/documentation/dev_guides/CC_Svcs_IG_BML_Supplement/html/

       ·   You'll want to add in the extra fields collected for BML. Suggested process is to use
           the remap feature in Vend::Payment::charge(). Thus, add to your route:

               Route foo remap <<EOV
                   bml_customer_registration_date bml_customer_registration_date
                   bml_customer_type_flag bml_customer_type_flag
                   bml_item_category bml_item_category
                   bml_product_delivery_type_indicator bml_product_delivery_type_indicator
                   bml_tc_version bml_tc_version
                   customer_ssn customer_ssn
                   date_of_birth date_of_birth
                   b_phone b_phone
               EOV

           This will allow those fields to be used directly from your form and be picked up by
           map_actual() for you. The names listed above correspond with the values as managed
           through SCMP. You can just as easily use, instead, those documented with Simple.

       ·   Set acct_type option to 'bml'.

       ·   On a failed BML attempt, the module sets [value suppress_bml] to 1. It's recommended
           you use this session setting to disable the BML option so as to encourage your
           customers to try to complete their order with a credit card.  Chances are extremely
           remote that a subsequent BML attempt will succeed after a failure. However, this is
           not a BML requirement; you may choose to let customers try again and again to check
           out with BML.

       ·   On a successful BML authorization, you can find the customer's BML account number
           (which looks like a credit card starting with the digits 5049) in
           $Session->{payment_result}{ccAuthReply_bmlAccountNumber}. Using this account number
           for repeat customers will speed up the authorization process, but it is not required.
           Without it, your BML customers will have to re-enter their last-four SSN and DOB each
           time.

           Note that BML does not consider this account number sensitive. It can be freely stored
           unencrypted in the customer's user record.

   Paypal
       This module also fully implements CyberSource's integration for Express Checkout services.
       Note that CyberSource doesn't appear to support all Paypal services, so depending on your
       needs (e.g., Mass Pay), you may need another option. However, for typical Express Checkout
       usage, it is fully supported.

       See CyberSource's full Paypal documentation for details:

       http://apps.cybersource.com/library/documentation/dev_guides/PayPal_Express_IG/html/

       ·   Set acct_type option to 'pp'

       ·   Module is set up to handle most standard cases with minimal demand on the developer.
           Paypal requires toting around the paypal session ID and, in the case of dopayment, the
           payer ID. Further, CyberSource requires that the request ID and token from the EC set
           be passed back on each subsequent request associated with the same paypal session.
           Finally, using address override needs to be tracked between a set call and subsequent
           get call. The module will track these values in the user's IC session and most likely
           "do the right thing". You can, however, override any of these explicitly if you have
           the need or wish to control it explicitly.

       ·   The reply fields are stripped down to their canonical values for convenience.  Many
           times, the same param merely differs in its reply field based on the application under
           which it was processed. E.g., the "amount" returned will come back in one of the
           following forms:

               payPalEcSetReply_amount
               payPalEcDoPaymentReply_amount
               payPalEcOrderSetupReply_amount
               payPalAuthorizationReply_amount
               payPalDoCaptureReply_amount

           Any of these will be stripped down to just "amount" in the payment_result hash, but
           the fully qualified parameter is left in place, too, if needed.

       ·   It is recommended that you utilize check_sub in conjunction with an EC get request for
           migrating response values from Paypal into the Interchange session.  The following is
           a sample sub that works in conjunction with a typical configuration based off the
           standard demo:

               Sub load_values <<EOS
               sub {
                   my ($resp, $req, $opt) = @_;

                   return unless $resp->{decision} eq 'ACCEPT';

                   my $b_pre = $Values->{pp_use_billing_address}
                       ? 'b_'
                       : ''
                   ;

                   $Values->{$b_pre . 'phone_day'}     = $resp->{payerPhone};

                   $Values->{email}            = $resp->{payer};
                   $Values->{payerid}          = $resp->{PayerId};
                   $Values->{payerstatus}      = $resp->{payerStatus};
                   $Values->{payerbusiness}    = $resp->{payerBusiness};
                   $Values->{salutation}       = $resp->{payerSalutation};
                   $Values->{mname}            = $resp->{payerMiddlename};
                   $Values->{suffix}           = $resp->{payerSuffix};
                   $Values->{address_status}   = $resp->{addressStatus};
                   $Values->{countryname}      = $resp->{countryName};

                   unless ($Session->{paypal_override}) {
                       $Values->{$b_pre . 'fname'}     = $resp->{payerFirstname};
                       $Values->{$b_pre . 'lname'}     = $resp->{payerLastname};
                       $Values->{$b_pre . 'address1'}  = $resp->{shipToAddress1};
                       $Values->{$b_pre . 'address2'}  = $resp->{shipToAddress2};
                       $Values->{$b_pre . 'city'}      = $resp->{shipToCity};
                       $Values->{$b_pre . 'state'}     = $resp->{shipToState};
                       $Values->{$b_pre . 'zip'}       = $resp->{shipToZip};
                       $Values->{$b_pre . 'country'}   = $resp->{shipToCountry};
                   }

                   return;
               }
               EOS

       ·   When making an EC set call through [charge], the module will return the appropriate
           URL to which to redirect the user's browser rather than the typical value of the
           transaction ID. Thus, when running an EC set, it is appropriate to capture and test
           the return value from [charge] to determine both if the request was successful and, if
           so, where to direct the user.

           Example mv_click code:

               [button
                   text="Checkout with Paypal"
                   form=basket
               ]
                   [tmp redirect][charge route=paypal_set][/tmp]
                   [if scratch redirect]
                       [bounce href="[scratch redirect]"]
                   [/if]
               [/button]

   Electronic Checks
       This module fully implements CyberSource's electronic check support. See documentation for
       full details:

       http://apps.cybersource.com/library/documentation/dev_guides/Electronic_Checks_IG/html/

       ·   Set acct_type option to 'ec'

       ·   Includes mappings to use the standard demo's default check payment option.

   Troubleshooting
       Try the instructions above in test mode (live set to anything but string 'true'). A test
       order should complete.

       Switch to production mode, then try an auth or sale with the card number "4111 1111 1111
       1111" and a valid expiration date. The transaction should be denied, and the reason should
       be in [data session payment_error].

       If nothing works:

       ·   Make sure you "Require"d the module in interchange.cfg:

               Require module Vend::Payment::CyberSource

       ·   Make sure all the modules/applications listed in PREREQUISITES are installed and
           working. You can test to see whether your Perl thinks they are:

               perl -MSOAP::Lite \
               -MXML::Pastor::Schema::Parser \
               -MLWP::Simple \
               -e 'print "It works\n"'

           If it prints "It works." and returns to the prompt you should be OK (presuming they
           are in working order otherwise).

       ·   Check the error logs, both catalog and global. Also set debugging on in
           "interchange.cfg" and check the debug log!

       ·   Make sure you set your payment parameters properly, and of course you used a payment
           route, right?

       ·   Try an order, then put this code in a page:

               <XMP>
               [calc]
                   my $string = $Tag->uneval( { ref => $Session->{payment_result} });
                   $string =~ s/{/{\n/;
                   $string =~ s/,/,\n/g;
                   return $string;
               [/calc]
               </XMP>

           That should show what happened.

       ·   If all else fails, consultants are available to help with integration for a fee.  See
           http://www.icdevgroup.org/ for mailing lists and other information.

BUGS

       Naturally none. OK, at least none known. Be sure to post any found to the IC user list or
       you can send them to the author directly.

AUTHOR

       Mark Johnson <mark@endpoint.com> (Based primarily off of Vend::Payment::ICS by Sonny Cook
       <sonny@endpoint.com>)