Integrating Siebel eSales with Third-Party Payment Applications

This chapter describes how to set up and use CyberSource, a third-party payment application that is supported by Siebel eSales. To use the CyberSource application, you must buy a separate license from CyberSource. You can also use other third-party applications for payment integration.

This chapter contains the following sections:

About CyberSource Internet Commerce Suite

Siebel eSales retrieves credit card information from CyberSource as part of the eSales - Authorize Order Process workflow (SS Authorize Order Process) when the customer clicks Confirm Order on the Order Summary page.

The CyberSource Internet Commerce Suite (ICS) is a set of third-party eCommerce applications. Siebel eSales uses the ICS to authorize credit card payments.

Siebel eSales accesses the ICS using an application programming interface (API), which is installed on the Siebel Application Interface. Messages are sent using CyberSource’s Simple Commerce Messaging Protocol (SCMP), which is based on Secure/Multipurpose Internet Mail Extensions (S/MIME), for authentication and encryption.

These messages contain a set of fields that describe the ICS application requests and provide information about the customer, the merchant, and the order form. SCMP messages are digitally signed and armored for transmission over an HTTP connection, allowing them to pass through firewalls and proxy servers.

For more information on the ICS, see Internet Commerce Suite Version 2 Application Programming Interface (API) Developer's Guide, which is available from the CyberSource Support Center (http://www.cybersource.com/support).

Note: You must obtain a merchant ID from CyberSource to access the Support Center.

Installing CyberSource Software

The steps to take for installing CyberSource are as follows:

Obtain a merchant ID.
Download the compressed file for the CyberSource Developer Kit (CDK) for your platform.
Install the CDK on the Siebel Server; set the system variables for the CDK and libraries.

For instructions on installing CyberSource applications, see the CyberSource documentation. For information on which versions of CyberSource software are supported by Siebel Business Applications, see Siebel System Requirements and Supported Platforms on Oracle Technology Network.

It is recommended that you download and use the latest version of CyberSource software from http://www.cybersource.com.

Enabling Credit Card Transactions with CyberSource

To enable credit card transactions, you must set Siebel Server object manager parameters.

To enable credit card transactions with CyberSource

Navigate to Server Administration > Components > Component Parameters.

Set the parameters for the eSales Object Manager as shown in the following table.

Parameter	Value
CCAEnable	TRUE
CCAMerchantId	merchant_id
CCAServerHost	ics2test.ic3.com
CCAType	CyberSourceICS2

CyberSource Integration with Siebel eSales

Integration of Siebel eSales with third-party payment applications involves three business services:

Credit Card Transaction Service (Universal Credit Card Service)
CyberSource Adapter Service
Shopping Service

This section contains the following topics:

Credit Card Transaction Service Business Service

The Credit Card Transaction Service process flow follows.

Siebel EAI passes data from a quote record and the method name to a Siebel output integration object.
The Siebel Data Transformation Engine maps the Siebel output integration object to a CyberSource input integration object.
The Siebel EAI XML Converter converts the vendor input integration object into XML, using the CC XML Converter Business Service, and passes the XML data and method name to the CyberSource Adapter Service.
The CyberSource Adapter Service business service processes the data, converts it into Siebel eScript, and passes it to CyberSource using the CyberSource API.
The CyberSource Adapter Service gets the payment information from CyberSource in Siebel eScript through the CyberSource API.
The CyberSource Adapter Service formats the payment information into an XML string.
The Siebel EAI XML Converter converts the XML into a vendor output integration object.
The Siebel Data Transformation Engine maps the vendor output integration object to a Siebel input integration object.
Siebel EAI updates the quote record with the payment information.

Business Service Methods

The Credit Card Transaction Service has business service methods for each of the following types of credit card transaction:

AuthCharge. This transaction authorizes and settles charges. It makes sure that the funds are available, reserves them, and requests that they be transferred in one call. It does this in the case of immediate order fulfillment (for example, digital downloads).
Authorization. Called from the eSales - Authorize Order Process workflow, this transaction allocates to the merchant a specific amount of the credit available to the cardholder, typically for one week. No funds are transferred.
The merchant authorizes a credit card to make sure of the following:
- The customer has the funds to pay for the purchase.
- These funds are reserved until the merchant is able to ship the product. Credit card companies typically state that a merchant should not settle until the product has been shipped.
- Charge. This transaction is used to settle charges. A settlement request includes the authorization code and requests that funds be transferred from the cardholder's account to the merchant's bank account.
- Process. This transaction is not used, but is available to customers for calling other methods from the third-party adapter.
- Refund. A refund takes place after a settlement when the merchant needs to transfer money back to the cardholder, as in the case of a return.
- Reverse. This transaction releases the amount of money reserved by an authorization. Although it is not supported by CyberSource, Reverse is important because authorizations reserve part of a cardholder's credit and therefore reduce the total amount of credit available.
  The arguments for these methods are:
  - Input:
    - Row Id
    - Siebel Input Integration Object
    - Siebel Output Integration Object
    - Siebel to Vendor Map Name
    - Vendor to Siebel Map Name
    - Vendor Name
  - Output:
    - Credit Card Response Code
    - Credit Card Response Message

Validate. Validation checks the credit card number, using the Mod 10 algorithm to make sure that it is valid, and the expiration date. The Siebel Business Application—not CyberSource—does this during rapid checkout and after selecting and saving payment information.
The arguments for Validate are:
- Input:
  - Credit Card Number
  - Credit Card Type
  - Expiration Month
  - Expiration Year
  - Return Error Code
- Output: Error Message

Business Service User Properties

The business service user properties specify the adapter business service to call, the configuration object to use, the vendor integration objects to use, and the text of the error messages. The active business service user properties are shown in the following table.

Business Service User Property	Value
Create Order on Web	1, 18, 19, 20, 21 These response codes will not return an error. Administrators should query for orders with these message types and investigate them manually. For more information, see Administering Siebel eSales
CyberSourceICS2:Adapter Business Service	CyberSource Adapter Service
CyberSourceICS2:AuthCharge Object (Vendor Input)	CreditCard - Authorization (CyberSource Input)
CyberSourceICS2:AuthCharge Object (Vendor Output)	CreditCard - AuthCharge (CyberSource Output)
CyberSourceICS2:Authorization Object (Vendor Input)	CreditCard - Authorization (CyberSource Input)
CyberSourceICS2:Authorization Object (Vendor Output)	CreditCard - Authorization (CyberSource Output)
CyberSourceICS2:Charge Object (Vendor Input)	CreditCard - Charge (CyberSource Input)
CyberSourceICS2:Charge Object (Vendor Output)	CreditCard - Charge (CyberSource Output)
CyberSourceICS2:Configuration Object	CreditCard - Configuration (CyberSource)
CyberSourceICS2:Refund Object (Vendor Input)	CreditCard - Refund (CyberSource Input)
CyberSourceICS2:Refund Object (Vendor Output)	CreditCard - Refund (CyberSource Output)
Response Message:1	Transaction was successful.
Response Message:2	Transaction was not successful. Please call your credit card company or try another credit card.
Response Message:3	Transaction was declined. Please select another credit card.
Response Message:4	There is a problem with this credit card. Please select another credit card.
Response Message:5	Your credit card has expired. Please select another card.
Response Message:6	Please check the credit card details or select another card.
Response Message:7	Your credit card is invalid. Please check the card details or select another credit card.
Response Message:8	Transaction declined by the bank. Please select another credit card.
Response Message:9	Your credit card number does not match the card type. Please check the card details or select another credit card.
Response Message:10	The billing address you entered does not match the billing address of your credit card. Please check the card details or select another card. This response is given when CyberSource returns DAVSNO. For more information, see Address Verification with Cyber Source.
Response Message:11	Please check to make sure you have entered complete credit card information.
Response Message:12	There is not enough available credit on this card. Please select another credit card.
Response Message:13	There was an error in processing. Please check the credit card information and try again or select another credit card.
Response Message:14	This type of credit card is not accepted. Please select another card.
Response Message:15	There is no corresponding, unused authorization record. Please authorize for this amount prior to settling.
Response Message:16	A credit or refund is only allowed when there is a corresponding settlement transaction referenced.
Response Message:17	Transaction has been settled, so it cannot be voided.
Response Message:18	You are not authorized to perform this transaction type.
Response Message:19	Error happened in adapter business service. Please contact your application administrator.
Response Message:20	Error occurred in CyberSource. Please contact your application administrator.
Response Message:21	The connection to CyberSource has timed out. Please try the operation later.

The complete response messages, and not the codes, are shown in the Siebel eSalesapplication.

For more information on modifying business service user properties, see Using Siebel Tools.

Integration Objects

Integration objects pass static or dynamic values to the business service. The architecture is modular in that you can create and use different integration objects for the same core business service.

The integration objects for the Quote and Order business components and CyberSource are detailed in this section.

Configuration

CreditCard - Configuration (CyberSource) has the user properties shown in the following table.

User Property	Value	Comments
VendorDll	ics2api	Do not use the prefix and extension. This is necessary for compatibility with Solaris.
customer_email	nobody@nowhere.com	CyberSource enforces the format.
customer_phone	(000) 000-0000	CyberSource requires at least six digits.
ignore_avs	no	CyberSource needs “yes” or “no.” This is only used for the AuthCharge transaction.
merchant_id	ICS2Test	CyberSource varchar(20), case-sensitive. Change this to your merchant ID. You can obtain a merchant ID for each division of your organization. The merchant IDs are set in the Divisions view under the Group Administration screen.
server_host	ics2test.ic3.com
server_port	80
timeout	90	In seconds. The default is 90.
decline_avs_flags	N	Comma-separated list of AVS codes that result in an AVS decline. For more information, see Address Verification with Cyber Source.

Authorization

CreditCard - Authorization (CyberSource Input). Its integration component is Invoice, as shown in the following table.

Fields	Fields	Fields
Amount	Bill To City	Bill To Country
Bill To State	Bill To Street Address	Bill To Street Address 2
Bill To Zipcode	Card Expiration Month	Card Expiration Year
Card Holder Name	Card Issue Number	Card Number
Card Start Month	Card Start Year	Card Verification Value
Currency Code	Duty Amount	Email Address
Ignore AVS	Ignore Bad CV	Merchant Id
National Tax	Phone Number	Product Code
Purchaser Code	Purchaser VAT Reg No	Quantity
Row Id	Ship From Zipcode	Ship To Country
Ship To Zipcode	Summary Commodity Code	Tax Amount
Tax Indicator	VAT rate

CreditCard - Authorization (CyberSource Output). Its integration component is Invoice, as described in the following table.

Fields	Fields
AVS	Application Resp Code
Application Resp Flag	Application Resp Msg
Authorization Code	Authorization Resp Code
Authorization Resp Flag	Authorization Resp Msg
Authorization Response	Authorized Amount
Authorized Time	CV Result
Request Id	Row Id

CreditCard - Payments. Its integration component is Credit Card Payments, as described in the following table.

Fields	Fields
Authorization Code	Bill To City
Bill To Country	Bill To State
Bill To Street Address	Bill To Street Address 2
Bill To Zipcode	Card Holder Name
Card Number	Card Type
Card Verification Number	Credit Card Response Code
Credit Card Transaction Amount	Credit Card Transaction ID
Credit Card Transaction Status	Credit Card Transaction Time
Credit Status	Credit Status Message
Currency Code	Expiration Month
Expiration Year	Merchant Id
Row Id	Transaction Id

CreditCard - Quote - Authorization (Siebel Input). Its integration component is Quote, as described in the following table.

Fields
Credit Card Authorization Code
Credit Card Transaction Amount
Credit Card Transaction ID
Credit Card Transaction Status
Quote Number

CreditCard - Quote - Authorization (Siebel Output). Its integration component is Quote, as described in the following table.

Fields	Fields
Amount	Bill To City
Bill To Country	Bill To State
Bill To Street Address	Bill To Street Address 2
Bill To Zipcode	Card Expiration Month
Card Expiration Year	Card Holder Name
Card Number	Card Type
Currency Code	Email Address
Home Phone	Quote Number
Work Phone

Settle (Charge)

CreditCard - Charge (CyberSource Input). Its integration component is Invoice, as described in the following table.

Fields	Fields
Amount	Auth Request Id
Authorization Code	Authorization Type
Currency Code	Duty Amount
Merchant Descriptor	Merchant Descriptor Contact
Merchant Id	National Tax
Product Code	Product Name
Purchaser Code	Purchaser VAT Reg No
Quantity	Row Id
Ship From Zipcode	Ship To Country
Ship To Zipcode	Summary Commodity Code
Tax Amount	Tax Indicator
VAT rate

CreditCard - Charge (CyberSource Output). Its integration component is Invoice, as described in the following table.

Fields	Fields
Application Resp Code	Application Resp Flag
Application Resp Msg	Charge Resp Code
Charge Resp Flag	Charge Resp Msg
Charge Trans Ref Number	Charged Amount
Charged Time	Request Id
Row Id

Authorize and Settle (AuthCharge)

CreditCard - AuthCharge (CyberSource Output). Its integration component is Invoice, as described in the following table.

Fields	Fields
AVS	Application Resp Code
Application Resp Flag	Application Resp Msg
Authorization Code	Authorization Resp Code
Authorization Resp Flag	Authorization Resp Msg
Authorization Response	Authorized Amount
Authorized Time	CV Result
Charge Resp Code	Charge Resp Flag
Charge Resp Msg	Charged Amount
Charged Time	Request Id
Row Id

CreditCard - Quote - AuthCharge (Siebel Input). Its integration component is Quote, as described in the following table.

Fields
Credit Card Transaction Amount
Credit Card Transaction ID
Credit Card Transaction Status
Quote Number

This integration object is not used out of the box. You can use CreditCard - Quote - Authorization (Siebel Input) for this method.

Refund

CreditCard - Refund (CyberSource Input). Its integration component is Invoice, as described in the following table.

Fields	Fields	Fields
Amount	Bill Request Id	Bill To City
Bill To Country	Bill To State	Bill To Street Address
Bill To Zipcode	Card Expiration Month	Card Expiration Year
Card Holder Name	Card Issue Number	Card Number
Card Start Month	Card Start Year	Currency Code
Duty Amount	Email Address	Merchant Descriptor
Merchant Descriptor Contact	Merchant Id	National Tax
Phone Number	Product Code	Purchaser Code
Purchaser VAT Reg No	Quantity	Row Id
Ship From Zipcode	Ship To Country	Ship To Zipcode
Summary Commodity Code	Tax Amount	Tax Indicator
VAT rate

CreditCard - Refund (CyberSource Output). Its integration component is Invoice, as described in the following table.

Fields	Fields
Application Resp Code	Application Resp Flag
Application Resp Msg	Refund Amount
Refund Auth Response	Refund Resp Code
Refund Resp Flag	Refund Resp Msg
Refund Time	Refund Trans Ref Number
Request Id	Row Id

For more information on integration objects, see Integration Platform Technologies: Siebel Enterprise Application Integration and Using Siebel Tools.

Data Maps

Data maps are used to map fields in one integration object to another integration object. The data maps used in credit card transactions are specified in the call to the business service.

You can view data maps by navigating to Integration Administration > Data Map Browser.

The data maps used in credit card transactions are shown in the following table.

Data Map	Source Integration Object	Target Integration Object
Authorization from Quote
CreditCardAuthorization_ Quote2CyberSource	CreditCard - Quote - Authorization (Siebel Output)	CreditCard - Authorization (CyberSource Input)
CreditCardAuthorization_ CyberSource2Quote	CreditCard - Authorization (CyberSource Output)	CreditCard - Quote - Authorization (Siebel Input)
Authorization from Payments
CreditCardAuthorization_ Payments2CyberSource	CreditCard - Payments	CreditCard - Authorization (CyberSource Input)
CreditCardAuthorization_ CyberSource2Payments	CreditCard - Authorization (CyberSource Output)	CreditCard - Payments
Charge from Payments
CreditCardCharge_ Payments2CyberSource	CreditCard - Payments	CreditCard - Charge (CyberSource Input)
CreditCardCharge_ CyberSource2Payments	CreditCard - Charge (CyberSource Output)	CreditCard - Payments
AuthCharge from Quote
CreditCardAuthorization_ Quote2CyberSource	CreditCard - Quote - Authorization (Siebel Output)	CreditCard - Authorization (CyberSource Input)
CreditCardAuthCharge_ CyberSource2Quote	CreditCard - AuthCharge (CyberSource Output)	CreditCard - Quote - AuthCharge (Siebel Input)
AuthCharge from Payments
CreditCardAuthorization_ Payments2CyberSource	CreditCard - Payments	CreditCard - Authorization (CyberSource Input)
CreditCardAuthCharge_ CyberSource2Payments	CreditCard - AuthCharge (CyberSource Output)	CreditCard - Payments
Refund from Payments
CreditCardRefund_ Payments2CyberSource	CreditCard - Payments	CreditCard - Refund (CyberSource Input)
CreditCardRefund_ CyberSource2Payments	CreditCard - Refund (CyberSource Output)	CreditCard - Payments

For more information on modifying integration objects and data maps, see Integration Platform Technologies: Siebel Enterprise Application Integration and Using Siebel Tools.

CyberSource Adapter Service Business Service

The CyberSource Adapter Service business service does the following:

Receives input from the Credit Card Transaction Service business service in XML format
Processes the data and uses Siebel eScript to call the CyberSource API
Gets the payment information from CyberSource using the CyberSource API
Passes XML data back to the Credit Card Transaction Service business service

The CyberSource Adaptor Service consists of methods, user properties, and scripts written in Siebel eScript:

Methods:
- Authorization, with arguments inputXML and outputXML
- Charge, with arguments inputXML and outputXML
- Refund, with arguments inputXML and outputXML
- Start, with argument outputXML
Scripts:
- (declarations). This script defines the variables used in the business service scripts.
- CallCyberSource. This script converts the XML to a property set, and then gets values from the property set to construct the message used by CyberSource. It calls CyberSource to get the result, uses the result to construct a property set, and then converts it to XML.
- FillOutIntObj. This script constructs the property set from the CyberSource result.
- FillRequestObj. This script constructs the CyberSource message from the property set.
- Initialize. This script initializes the variables for the service. Variables to initialize are passed in by setting the values in the CreditCard - Configuration (CyberSource) integration object user properties.
- LogMessage. This script writes to the log file the buffers that are passed to CyberSource and received from CyberSource, if the Debug flag is set.
- SendCmd. This script calls CyberSource with a different method.
- Service_PreInvokeMethod. This is the starting point where the business service is called.
- SetResponseCode. This script maps CyberSource error flags to Siebel response codes.
- ThrowError. This script generates the error messages that are set up in the Credit Card Transaction Service business service user properties.

To examine the Siebel eScripts in the CyberSource Adapter Service business service, right-click the business service in Siebel Tools, and then choose Edit Server Scripts.

For more information on Siebel eScripts, see Siebel Tools Online Help.

Address Verification with Cyber Source

Address Verification will fail when CyberSource returns DAVSNO as the reply code. When DAVSNO is returned, an authorization code will still be returned to your Siebel Business Application. You can use the values for the decline_avs_flags business service user property to indicate which address verification results should result in DAVSNO being returned by CyberSource. From Siebel eSales, N is passed to CyberSource, indicating that when this result is received by CyberSource for the address verification check, DAVSNO will be returned to your Siebel Business Application. To indicate that other address verification responses should result in DAVSNO being returned to your Siebel Business Application, add the values to the decline_avs_flags business service user property. If you want to authorize and settle at the same time, you can indicate that address verification results should be ignored by setting the ignore_avs business service user property to yes.

Customizing Cybersource Integration

You can customize Siebel eSales integration with CyberSource. Some examples are modifying scripts, passing more fields to CyberSource, and performing credit card processing on data in other business components.

This section contains the following topics:

Modifying the Scripts in the CyberSource Adapter Service

As the scripts in the CyberSource Adapter Service are written in Siebel eScript, they can be readily modified.

For more information on Siebel eScripts, see Siebel Tools Online Help. For more information on debugging scripts, see Using Siebel Tools.

To modify scripts in the CyberSource Adapter Service business service

In Siebel Tools, lock the EAI CreditCard project.
Select the Business Service object.
Select the CyberSource Adapter Service, copy it, and then rename the copy as a backup.
Right-click CyberSource Adapter Service, and then choose Edit Server Scripts.
The server script editor appears.
Edit the desired scripts, and then close the edit window.
Compile the Siebel runtime repository file, selecting the Locked projects radio button.

Passing Data from Other Fields in the Siebel Database

You can add data fields to those passed to CyberSource.

For more information on modifying integration objects, see Integration Platform Technologies: Siebel Enterprise Application Integration. For more information on modifying scripts, see Using Siebel Tools.

To add a data field

In Web Tools, add the field to the appropriate Cybersource input and output integration objects.
Modify the (declarations) script in the CyberSource Adapter Service business service to add the field to the correct output object, for example ICS2OBJS[“Authorization”].OutputFields.
In your Siebel Business Application, navigate to Integration Administration > Data Map Editor.
Update the data map so that data from the appropriate Siebel field will be passed to the CyberSource integration object.

Passing Data from Fields Not in the Siebel Database

There are three ways to pass data from fields that do not exist in the Siebel database:

Add the field to the database, add it to the necessary integration object, and then update the data map.
Set an existing business service user property in the Credit Card Transaction Service business service, or create a new one, with a static value for all transactions. These values are read upon initialization of the business service.
Any data passed dynamically using the integration objects will overwrite the value in the business service user property for that particular transaction.
Set a value for an integration object field by setting the value in the data map.
You cannot set a default value for an integration object user property because the Credit Card Transaction Service business service does not look for this value at initialization.

Note: The auth_cv_result reply field contains details of the card verification check. This data is not stored in the Siebel database but you can use it to store additional information or drive additional logic.

Calling the Credit Card Transaction Service from Other Places in Siebel eSales

You can call a business service from any of the following:

Button, as long as the applet that contains this button is based on the CSSBCBase class
Workflow
Script, either Siebel eScript or Siebel VB

To call the Credit Card Transaction Service business service

Use the GetService() method to get an instance of the business service.
Use Service_InvokeMethod() to invoke a method of the business service.
Use SetProperty() to pass values for the business service method arguments that need to be set.
See Business Service Methods for the business service method arguments of the Credit Card Transaction Service.

Calling the Credit Card Transaction Service from Other Business Components

You can call the Credit Card Transaction Service business service from other business components besides Quote and Order.

To call the Credit Card Transaction Service from another business component

Choose where to call the business service (button, workflow, or script).
In Siebel Tools, create integration objects for the business component to pass the correct data to the business service.
In your Siebel Business Application, navigate to Integration Administration > Data Map Editor.
Create integration object maps for the business component integration objects.

Using Other Third-Party Payment Applications

Using other payment services requires modifying the CyberSource Adapter Service business service or writing a new one. Because the scripts in the CyberSource Adapter Service are in Siebel eScript, you can readily modify them.

For more information on Siebel eScripts, see Siebel Tools Online Help. For more information on business services and on debugging scripts, see Using Siebel Tools.

Note: After creating the new payment business service, you must create or modify integration objects and data maps for it.

To create a new payment business service

In Web Tools, lock the EAI CreditCard project.
Select the Business Service object.
Select the CyberSource Adapter Service and copy it.
Rename the copy, for example New Payment Adapter.
Right-click New Payment Adapter, and then choose Edit Server Scripts.
The server script editor appears.
Modify the desired scripts, and then close the edit window.
Edit the business service user properties of the Credit Card Transaction Service Business Service to call the New Payment Adapter business service.
Save the changed and submit the workspace for delivery.