Oracle® Retail Open Commerce Platform

OCP/CyberSource Integration Implementation Guide

Release 6.0.1

February 2015
 Oracle® Retail Open Commerce Platform OCP/CyberSource Integration Implementation Guide,
Release 6.0.1

Note: The rebranding for the latest version of this documentation set is in development as part of post
MICROS acquisition activities. References to former MICROS product names may exist throughout this
existing documentation set.

Copyright © 2015, Oracle and/or its affiliates. All rights reserved.

Primary Author:

Contributors:

This software and related documentation are provided under a license agreement containing
restrictions on use and disclosure and are protected by intellectual property laws. Except as expressly
permitted in your license agreement or allowed by law, you may not use, copy, reproduce, translate,
broadcast, modify, license, transmit, distribute, exhibit, perform, publish, or display any part, in any
form, or by any means. Reverse engineering, disassembly, or decompilation of this software, unless
required by law for interoperability, is prohibited.

The information contained herein is subject to change without notice and is not warranted to be error-
free. If you find any errors, please report them to us in writing.

If this software or related documentation is delivered to the U.S. Government or anyone licensing it on
behalf of the U.S. Government, then the following notice is applicable:

U.S. GOVERNMENT END USERS: Oracle programs, including any operating system, integrated
software, any programs installed on the hardware, and/or documentation, delivered to U.S.
Government end users are "commercial computer software" pursuant to the applicable Federal
Acquisition Regulation and agency-specific supplemental regulations. As such, use, duplication,
disclosure, modification, and adaptation of the programs, including any operating system, integrated
software, any programs installed on the hardware, and/or documentation, shall be subject to license
terms and license restrictions applicable to the programs. No other rights are granted to the U.S.
Government.

This software or hardware is developed for general use in a variety of information management
applications. It is not developed or intended for use in any inherently dangerous applications, including
applications that may create a risk of personal injury. If you use this software or hardware in dangerous
applications, then you shall be responsible to take all appropriate fail-safe, backup, redundancy, and
other measures to ensure its safe use. Oracle Corporation and its affiliates disclaim any liability for any
damages caused by use of this software or hardware in dangerous applications.

Oracle and Java are registered trademarks of Oracle and/or its affiliates. Other names may be
trademarks of their respective owners.

Intel and Intel Xeon are trademarks or registered trademarks of Intel Corporation. All SPARC
trademarks are used under license and are trademarks or registered trademarks of SPARC
International, Inc. AMD, Opteron, the AMD logo, and the AMD Opteron logo are trademarks or
registered trademarks of Advanced Micro Devices. UNIX is a registered trademark of The Open Group.

This software or hardware and documentation may provide access to or information on content,
products, and services from third parties. Oracle Corporation and its affiliates are not responsible for
and expressly disclaim all warranties of any kind with respect to third-party content, products, and
services unless otherwise set forth in an applicable agreement between you and Oracle. Oracle
Corporation and its affiliates will not be responsible for any loss, costs, or damages incurred due to
your access to or use of third-party content, products, or services, except as set forth in an applicable
agreement between you and Oracle.

OCP/CYBERSOURCE INTEGRATION IMPLEMENTATION GUIDE 2

All information contained within this document is proprietary and confidential.
Table of Contents

1. Introduction ................................................................................................................. 4

2. Project Planning and Resources .............................................................................. 4

2.1. Initial Steps ............................................................................................................. 4
2.2. Project Activities ..................................................................................................... 4

3. Implementation ........................................................................................................... 4
3.1. CyberSource Access.............................................................................................. 4
3.2. Determine Decision Manager Usage ..................................................................... 5
3.3. Site Parameter Configuration ................................................................................. 6
3.3.1. Enable CyberSource Payments ...................................................................... 7
3.3.2. Configure Security Keys .................................................................................. 7
3.3.3. Configure Merchant Identification .................................................................... 7
3.3.4. Configure Transaction Identifier ...................................................................... 8
3.3.5. Configure CyberSource Version ...................................................................... 9
3.3.6. Configure Production or Test Server ............................................................... 9
3.3.7. Configure Number of Authorization Retry Attempts ...................................... 10
3.3.8. Configure Logging ......................................................................................... 10
3.3.9. Configure Order Total Usage ........................................................................ 11
3.3.10. Configure Decision Manager Support ......................................................... 12
3.3.11. Configure Advanced Fraud Service Usage ................................................. 12
3.3.12. Configure CVC (Card Verification Code) Usage ......................................... 13
3.3.13. Configure AVS (Address Verification Service) Usage................................. 13
3.4. Error Message Configuration ............................................................................... 14
3.5. Conversion Detail Report Configuration .............................................................. 14
3.5.1. Decision Manager Status Update .................................................................. 14
3.6. Configure Batch Processes ................................................................................. 15
3.6.1. Reauthorization Process ............................................................................... 16
3.6.2. Settlement Process ....................................................................................... 16
3.7. Testing information............................................................................................... 16
3.7.1. Test Credit Cards .......................................................................................... 16
3.7.2. Test Scenarios ............................................................................................... 17

OCP/CYBERSOURCE INTEGRATION IMPLEMENTATION GUIDE 3

All information contained within this document is proprietary and confidential.
1. INTRODUCTION
Base OCP contains the functionality to connect with the development instance of CyberSource for payment
processing. This document describes how to enable the connectivity so that credit card authorizations can be
done in any environment.
OCP connects to a FDC Nashville Processor Simulator to test credit card authorizations. Prior to using this
processor, a client implementation should create an evaluation account with CyberSource:
http://www.cybersource.com/register/.

2. PROJECT PLANNING AND RESOURCES

This document provides a guide to implementing the CyberSource functionality that is integrated with the
Open Commerce Platform (OCP).

This document assumes that CyberSource is being implemented on a new product build based on OCP
version 5.1 or newer.
2.1. Initial Steps
As soon as there is a commitment to an OCP implementation and it is confirmed CyberSource is included:

• Obtain the proposal and contract documents to confirm details of the CyberSource implementation
and if it is base or includes additional enhancements.

2.2. Project Activities

Key activities per implementation team roles are defined below for the base OCP CyberSource integration.

Project Management:
• Create a ticket for Managed Services to have the firewall opened for access to CyberSource.
• Ensure the client has an account with CyberSource. Information on registering with CyberSource can
be found here: http://support.cybersource.com/cybskb/index?page=content&id=C887&actp=RSS.
• Determine if the client will be using Decision Manager.

Development and Interface Design:

• Configure the site parameters for CyberSource;
• Configure the environment variables for the website as well as the batch processes;
• Schedule the batch processes to run.

Quality Assurance Testing

• Test order taking, returns, appeasements, and settlements using credit cards.
• Verify that re-authorizations occur when needed and that re-authorization rejections are handled
correctly.
• Use the test scenarios in this document to confirm that authorization rejections occur and are handled
correctly.

3. IMPLEMENTATION
3.1. CyberSource Access
Create a Managed Services request to have the firewall opened for access to CyberSource.

OCP/CYBERSOURCE INTEGRATION IMPLEMENTATION GUIDE 4

All information contained within this document is proprietary and confidential.
3.2. Determine Decision Manager Usage
CyberSource provides an application named “Decision Manager”. Decision Manager provides enhanced
support for reviewing authorization requests for fraud potential. It also provides an interface for a user to
review authorizations that have been flagged as fraud risks and to accept or reject those requests. Additional
information on Decision Manager can be found here:
http://www.cybersource.com/products_and_services/fraud_management/decision_manager/.
When Decision Manager is used with OCP, authorization requests can be returned with a status that indicates
Decision Manager has flagged it for a potential fraud. The order associated with the authorization request is
then given a “Decision Manager Hold” status, which prevents fulfillment of the order from taking place.
Authorization requests are then examined within Decision Manager, and are either approved or rejected.
When the approval or rejection is received by OCP, the order is removed from hold and either fulfilled or
cancelled.

OCP/CYBERSOURCE INTEGRATION IMPLEMENTATION GUIDE 5

All information contained within this document is proprietary and confidential.
3.3. Site Parameter Configuration
There are a number of site parameters that need to be set in order for communication to work correctly with
CyberSource. All of the parameters are set in the Site Manager, in the “Content -> Site Configurations”
section. Edit the site that will be connected to CyberSource, and navigate to the “Parameters” page for the
site.

Each parameter can be set by selecting either the parameter name or the parameter value. On the page that
appears, enter the new value for the parameter, then select “Save Parameter”.

The sections below describe the parameters and how their values should be set.

OCP/CYBERSOURCE INTEGRATION IMPLEMENTATION GUIDE 6

All information contained within this document is proprietary and confidential.
3.3.1. Enable CyberSource Payments

The “PAYMENTSERVICE.CC.CYBERSOURCE.PAYMENT.ENABLED” parameter needs to be set to “true” in

order to use CyberSource for payments.

3.3.2. Configure Security Keys

The “ENV.PAYMENTSERVICE.CC.CYBERSOURCE.KEYSDIRECTORY” parameter should be set to the

directory that contains the security keys that were created for CyberSource. It is recommended that this
directory be a local directory for performance reasons. The keys will be included in each communication with
CyberSource. Note that CyberSource requires that forward slashes must be used in the directory path, even
on Windows systems. Information on creating keys can be found at:
http://apps.cybersource.com/library/documentation/dev_guides/security_keys/html/wwhelp/wwhimpl/js/html/w
whelp.htm.

3.3.3. Configure Merchant Identification

The “PAYMENTSERVICE.CC.CYBERSOURCE.MERCHANTID” parameter should be set to the merchant

identifier of the site.

OCP/CYBERSOURCE INTEGRATION IMPLEMENTATION GUIDE 7

All information contained within this document is proprietary and confidential.
3.3.4. Configure Transaction Identifier

The “PAYMENTSERVICE.CC.CYBERSOURCE.FINGERPRINT.ENABLED” parameter should be set to

“true” if the site wants to store a device fingerprint in each transaction. A device fingerprint helps identify the
source of authorization requests, which can be valuable when someone is attempting to fraudulently make
multiple purchases from the same machine by spoofing values such as the city and state the purchase is
taking place in. If set to “true”, the pipeline session identifier will be stored as the device fingerprint in the
CyberSource transaction. If set to “false”, it will not be included. Additional information on device fingerprints
can be found here:
https://support.cybersource.com/cybskb/index?page=content&id=C740&actp=search&viewlocale=en_US&se
archid=1378823060725.

OCP/CYBERSOURCE INTEGRATION IMPLEMENTATION GUIDE 8

All information contained within this document is proprietary and confidential.
3.3.5. Configure CyberSource Version

The “PAYMENTSERVICE.CC.CYBERSOURCE.TARGETAPIVERSION” parameter should be set to the

version of CyberSource Simple Order API that is being used. The Simple Order API is the name of the API
that is used to communicate with CyberSource.

3.3.6. Configure Production or Test Server

The “PAYMENTSERVICE.CC.CYBERSOURCE.SENDTOPRODUCTION” parameter should be set to “true” if

transactions should be sent to the CyberSource production server. Set the value to “false” if they should be
sent to the test server. The test server is the FDC Nashville Processor Simulator, or one of the other
simulation processors that CyberSource provides.

OCP/CYBERSOURCE INTEGRATION IMPLEMENTATION GUIDE 9

All information contained within this document is proprietary and confidential.
3.3.7. Configure Number of Authorization Retry Attempts

The “PAYMENTSERVICE.CC.CYBERSOURCE.MAXAUTHENTICATIONATTEMPTS” parameter should be

set to an integer that indicates the maximum number of times to try to authenticate a transaction. This is used
only when there are communication errors in the authentication attempt.

3.3.8. Configure Logging

The “PAYMENTSERVICE.CC.CYBERSOURCE.ENABLELOG” parameter should be set to “true” if

CyberSource should generate transaction logs, “false” if it should not. CyberSource provides the following
information on logging in the client developer guide
(http://apps.cybersource.com/library/documentation/dev_guides/Simple_Order_API_Clients/Client_SDK_SO_
API.pdf).
The “PAYMENTSERVICE.CC.CYBERSOURCE.LOGMAXIMUMSIZE” parameter should be set to the
maximum size in megabytes that the log file can grow to. When the log file reaches this size, CyberSource
will archive it and start a new file. The archive filename will take the form of
“cybs.log.<yyyymmddThhmmssxxx>”, where xxx is milliseconds.

The “ENV.PAYMENTSERVICE.CC.CYBERSOURCE.LOGDIRECTORY” parameter should be set to the

directory where log files should be placed. Note that CyberSource requires that forward slashes must be
used in the directory path, even on Windows systems.

OCP/CYBERSOURCE INTEGRATION IMPLEMENTATION GUIDE 10

All information contained within this document is proprietary and confidential.
3.3.9. Configure Order Total Usage

The “PAYMENTSERVICE.CC.CYBERSOURCE.ONEDOLLARMODE” parameter should be set to “true” if

authentications will be done using a fake price. This should be set to “false” to use the actual order total in
the authentication. Note – usage of this parameter is not fully implemented in OCP and the value should
therefore always be “false”.

OCP/CYBERSOURCE INTEGRATION IMPLEMENTATION GUIDE 11

All information contained within this document is proprietary and confidential.
3.3.10. Configure Decision Manager Support

The “PAYMENTSERVICE.CC.CYBERSOURCE.ALLOWDECISIONMANAGERFORFRAUDCHECK”
parameter should be set to true” if CyberSource’s Decision Manager application is being used. When set to
“true”, the processing of the return values from authorization requests is modified to include Decision
Manager review as a valid return. Setting this to true does NOT tell CyberSource to use the Decision
Manager. Set the value to “false” if Decision Manager is not being used.

3.3.11. Configure Advanced Fraud Service Usage

The “PAYMENTSERVICE.CC.CYBERSOURCE.RUNAFSSERVICE” parameter should be set to “true” if the

site is using CyberSource’s Advanced Fraud Service. It should be set to “false” if it is not. Setting it to “true”
will prompt CyberSource to use the Advanced Fraud Service when running authorizations.

OCP/CYBERSOURCE INTEGRATION IMPLEMENTATION GUIDE 12

All information contained within this document is proprietary and confidential.
3.3.12. Configure CVC (Card Verification Code) Usage

The “PAYMENTSERVICE.CC.CYBERSOURCE.USECVC” parameter should be set to “true” if you want to

use CVC (Card Verification Code) verification when authorizing transactions. If using it, the customer’s CVV
number must be captured during checkout. The CVV code will be compared with the CVV code on file with
the credit card issuer. Set it to “false” to not use it.

3.3.13. Configure AVS (Address Verification Service) Usage

The “PAYMENTSERVICE.CC.CYBERSOURCE.USEAVS” parameter should be set to “true” if you want to

use AVS (Address Verification Services) when authorizing transactions. If using it, the customer’s billing
address must be captured during checkout. The billing address will compared against the billing address on
file with the credit card issuer. Set it to “false” to not use it.
The “PAYMENTSERVICE.CC.CYBERSOURCE.AVSFLAGS” parameter should be set to a space-delimited
set of AVS codes that will prompt the authorization to be declined for AVS reasons. The AVS system returns

OCP/CYBERSOURCE INTEGRATION IMPLEMENTATION GUIDE 13

All information contained within this document is proprietary and confidential.
a defined set of codes, and this parameter should be set to the returned AVS codes that will be interpreted as
an AVS failure. AVS codes are standardized and can be found online in many places.
The “PAYMENTSERVICE.CC.CYBERSOURCE.AVSLEVEL” parameter should be set to “Standard”,
“Enhanced”, or “AAV+”. This sets the level of address verification used for the authentication. For
“Enhanced” or “AAV+”, you need to use the American Express Phoenix gateway.

3.4. Error Message Configuration

Cybersource returns a number of codes that describe the results of a credit card authorization. These error
codes are listed here: https://support.cybersource.com/cybskb/index?page=content&id=C156.
OCP maintains a set of error messages for the return codes that may be customized by an implementation
team. The error codes are contained in the OCP PaymentServiceProviderCybersourceImpl class.
Implementation teams can extend or replace this class with one of their own with customized error messages.
If Decision Manager is being used, there are only two return codes that indicate Decision Manager has
flagged the card and will not authorize the transaction. The OCP error messages in these cases are generic,
as detailed information on the reason for the issue with the credit card is not returned from CyberSource.
Implementation teams should configure their error messages appropriately.

3.5. Conversion Detail Report Configuration

3.5.1. Decision Manager Status Update

Decision Manager creates a report that details the transactions that have been accepted and rejected in it.
The OCP Decision Manager status update batch process reads in the report, and then processes the
transactions and the orders associated with them appropriately. When Decision Manager is being used, the
Decision Manager status update batch process needs to be scheduled and configured appropriately.
There are two different processes, one that runs on demand
(oms-decision-manager-update-status-ondemand.sh) and one that runs daily
(oms-decision-manager-update-status-daily.sh). Both processes share the same configuration file,
shell-decision-manager-status-update-config.xml. The environment variables for the conversion detail report
must be configured in order for these processes to run successfully. These variables should be set in the
site’s context.xml and the batch process’s configuration file. The variables are:

OCP/CYBERSOURCE INTEGRATION IMPLEMENTATION GUIDE 14

All information contained within this document is proprietary and confidential.
 • cybersource.cdr.service.url.daily should be set to the URL on CyberSource where the conversion
detail report will be located.

• cybersource.cdr.service.url.ondemand should be set to the URL of the CyberSource application that

will create a conversion detail report on demand.

• cybersource.cdr.service.merchantId should be set to the CyberSource merchant identifier for the

site.

• cybersource.cdr.service.username should be set to the CyberSource username that is used for

access to the report.

• cybersource.cdr.service.password should be set to the CyberSource password that is used for

access to the report.

• cybersource.cdr.service.timezone should be set to the time zone of the location where the batch
process is being executed. The time zone should be in Greenwich Mean Time, i.e."GMT-04:00".

• cybersource.cdr.service.onDemandRange should be set to the number of minutes of data to pull for

on demand reports. The number of minutes indicates the number of minutes different from the
current time, so to pull data for the previous two hours, the value should be set to “-120”.

• cybersource.cdr.service.cancel.note should be set to string to that contains information that will be

will be stored as notes if the authorization is rejected from within Decision Manager. When an
authorization is rejected, the order associated with it is release from hold, and then cancelled. The
string set as the cancel notes will be saved with both the request to release the order from hold and
the request to cancel the order.

• cybersource.cdr.service.adminUserId should be set to the user ID of the administrative user that

should be stored as the user if the authorization is approved. When an authorization is approved in
Decision Manager, the order associated with the authorization has its status changed from
“Decision Manager Hold” and the fulfillment of the order can proceed. When the order is released
from its hold state, the administrative user ID is saved with the hold release.

• cybersource.cdr.service.parser.namespaceAware should be set to “true” if the SAX parser that is

used to parse the report returned from CyberSource should be namespace aware, and “false” if it
should not be. The recommended setting is “true”.

• cybersource.cdr.service.parser.validate should be set to “true” if the SAX parser that is used to

parse the report returned from CyberSource should validate the XML as it is parsing it. Set it to
“false” if it should not validate the XML. The recommended setting is “true”.

• cybersource.cdr.mail.to is defined in configuration files, but not used in OCP. It does not need to be
modified for a client.

• cybersource.cdr.mail.from is defined in configuration files, but not used in OCP. It does not need to
be modified for a client.

• cybersource.cdr.mail.subject is defined in configuration files, but not used in OCP. It does not need
to be modified for a client.

• mail.emailServer is defined in configuration files, but not used in OCP. It does not need to be
modified for a client.

3.6. Configure Batch Processes

The following batch processes must also be configured to run. These are not specific to CyberSource, but
are necessary in order for payments, reauthorizations, and settlements to be processed correctly.

OCP/CYBERSOURCE INTEGRATION IMPLEMENTATION GUIDE 15

All information contained within this document is proprietary and confidential.
3.6.1. Reauthorization Process

Although not specific to CyberSource, the reauthorization process needs to be scheduled to run in order for
payments and settlements to work correctly. The reauthorization process attempts to get new authorizations
for authorizations that have expired, or authorizations that had communication errors on their initial
authorization attempt. The shell script for the reauthorization process is named oms-reauthorization.sh and
its configuration file is named shell-oms-reauthorization-config.xml.
3.6.2. Settlement Process

Although not specific to CyberSource, the settlement process needs to be scheduled to run in order for
settlements to be processed. The shell script for the settlement process is named oms-settlement.sh and the
configuration file is named shell-oms-settlement-config.xml.

3.7. Testing information

3.7.1. Test Credit Cards

The following credit card numbers can be used in testing. These are not real credit cards, but will
authorize as if they were. Never use a real credit card for testing purposes.

Credit Card Test Number

American Express 3782 8224 6310 005

Discover 6011 1111 1111 1117

JCB 3566 1111 1111 1113

Laser 6304 9850 2809 0561 515

Maestro (International) 5033 9619 8909 17

5868 2416 0825 5333 38

Maestro (UK Domestic) Issue number not required: 6759 4111 0000 0008
One-digit issue number required: 6759 5600 4500 5727 054
Two-digit issue number required: 5641 8211 1116 6669

MasterCard 5555 5555 5555 4444

Solo Issue number not required: 6334 5898 9800 0001

One-digit issue number required: 6767 8200 9988 0077 06
Two-digit issue number required: 6334 9711 1111 1114

UATP 1354 1234 5678 911

Visa 4111 1111 1111 1111

OCP/CYBERSOURCE INTEGRATION IMPLEMENTATION GUIDE 16

All information contained within this document is proprietary and confidential.
3.7.2. Test Scenarios
You can simulate authorization rejections by checking out with scenarios that are configured to produce a
rejection. See example scenarios configured for the FDC Nashville Processor Simulator for additional
information on the scenarios that will trigger a rejection. Sample scenarios for both approved and rejected
cases are also listed below.

Scenario CyberSource Response OCP Response

Master Card: decision=REJECT Display error message ”We are

5555 5555 5555 4444 reasonCode=233 sorry we cannot process your
Expiration: 08/2013 ccAuthReply_processorResponse=D80 order at this time. Please verify
CVV: 1111 the credit card number and
Grand total amount: 1500.00 expiration date that you
entered. If you have entered
your credit card information
correctly, please contact your
credit card company for an
explanation. Please use
another credit card if you
continue to receive this
message.”
Master Card: decision=ACCEPT Continue checkout process
5555 5555 5555 4444 reasonCode=100
Expiration: 08/2013 ccAuthReply_authorizationCode=123456
CVV: 1111 ccAuthReply_processorResponse=A
Grand total amount: 29.95 ccAuthReply_amount=29.95
American Express: decision=ERROR Display error message: “We are
3782 8224 6310 005 reasonCode=150 sorry, but the credit card
Expiration: 08/2013 ccAuthReply_processorResponse=E01 authorization system is unable
CVV: 1111 to process authorizations at this
Grand total amount: 2001.00 time. Please try again later.”

American Express: decision=ACCEPT Continue checkout process

3782 8224 6310 005 reasonCode=100
Expiration: 08/2013 ccAuthReply_authorizationCode=123456
CVV: 1111 ccAuthReply_processorResponse=A
Grand total amount: 332.47 ccAuthReply_amount=332.47
Visa: decision=REJECT Display error message ”We are
4111 1111 1111 1111 reasonCode=234 sorry we cannot process your
Expiration: 08/2013 ccAuthReply_processorResponse=E03 order at this time. Please verify
CVV: 1111 the credit card number and
Grand total amount: 2003.00 expiration date that you
entered. If you have entered
your credit card information
correctly, please contact your
credit card company for an
explanation. Please use
another credit card if you
continue to receive this
message.”

OCP/CYBERSOURCE INTEGRATION IMPLEMENTATION GUIDE 17

All information contained within this document is proprietary and confidential.
 Scenario CyberSource Response OCP Response

Visa: decision=ACCEPT Continue checkout process

4111 1111 1111 1111 reasonCode=100
Expiration: 08/2013 ccAuthReply_authorizationCode=123456
CVV: 1111 ccAuthReply_processorResponse=A
Grand total amount: 349.96 ccAuthReply_amount=349.96

OCP/CYBERSOURCE INTEGRATION IMPLEMENTATION GUIDE 18

All information contained within this document is proprietary and confidential.