Cybersource API integration documentation

This document will explain how we can integrate Cybersource API into our application by setting the required Request parameters and invoking the end point url for making a SOAP call to Cybersource API to perform different operations like Payment transactions; Saving/ Retrieving customer credit card details; on-demand transaction and converting an existing transaction to customer profile.

Packages & JARS usedWe are using Apache Axis and WSS4J toolkit for constructing and making the SOAP web service call to Cybersource.

Packages Used Packages used Description

Apache Axis 1.4 SOAP toolkitDownload and unzip the latest package from http://ws.apache.org/axis

Apache WSS4J 1.5.1 WS-Security packageDownload and unzip the latest package from http://ws.apache.org/wss4j

activation.jar JDK JavaBeans Activation Framework add-on that you can download from http://www.oracle.com/technetwork/java/jaf11-139815.html

Apache XML Security 1.4.0

XML security packageDownload the latest package from http://santuario.apache.org/download.html and extract xmlsec-N.N.N.jar

JARS Used Packages JARS

Apache Axis axis.jarcommons-discovery-0.2.jarcommons-logging-1.0.4.jarjaxrpc.jarlog4j-1.2.8.jarsaaj.jarwsdl4j-1.5.1.jar

Apache WSS4J wss4j-1.5.1.jar

Generating and Building the Stubs.

We have to generate Stubs from the wsdl file downloaded from the Cybersource. The steps are as follows:

Step 1. Download the Cybersource Sample code from:http://www.cybersource.com/support_center/implementation/downloads/soap_api/sample_files/sample_axis_wss4j.zip

# File description in Sample code:a. Sample.java : sample file, which provides the code to process your transactions. The file contains comments and a sample card authorization.

b. SamplePWCallback.java : sample Password Callback Handler, which provides the password to WSS4J.c. SampleDeploy.wsdd : sample deployment descriptor file used by WSS4J.

Step 2. From a command prompt, go to the directory where you downloaded the CyberSource sample code Sample.java.

Step 3. To generate the stubs, execute this command without line breaks:java org.apache.axis.wsdl.WSDL2Java -p com.cybersource.stub https://ics2wsa.ic3.com/commerce/1.x/transactionProcessor/CyberSourceTransaction_1.123.wsdl

Here, com.cybersource.stub is the package name that will be used for the generated classes and the latest wsdl version is located at:https://ics2wsa.ic3.com/commerce/1.x/transactionProcessor/CyberSourceTransaction_1.123.wsdl

Step 4. To compile the source code, execute this command:javac com/cybersource/stub/*.java

Step 5. Create a jar file by using the compiled classes:jar cf cybersource.jar com/cybersource/stub/*.class

Step 6. Add the newly created cybersource.jar to your classpath.

#Note: The JAVA classes (stub) form wsdl can be generated by following this stepRightClick on any Project->Create New Other ->Web Services->Web Service Client->Then paste the wsdl url(or location) in Service Definition->Next->Finish

Building the Sample and Testing the Client.

To build the sample and test your client, modify the variables in the sample files, and run the application.

Step 1 In Sample.java, modify the values of MERCHANT_ID.Step 2 In SamplePWCallback.java, modify the value of TRANSACTION_KEY.Step 3 Compile the samples as follows: javac Sample.java SamplePWCallback.javaStep 4 Run the sample as follows: java -Daxis.ClientConfigFile=SampleDeploy.wsdd Sample

The reply file contains the request result and all returned fields. When testing the client is finished, write the code to use the client application.

#Note: The MERCHANT_ID & TRANSACTION_KEY are obtained through the Cybersource Business Center account which is explained in the below section.

Cybersource Test Business Center steps:

Url: https://ebctest.cybersource.com/ebctest/login/

We need to create a Cybersource merchant account to test out our transactions and retrieve a “ Merchant ID” and “Transaction Key”. After creating an account and obtaining the Merchant ID (assigned automatically to a newly created account), the steps to create the Transaction Key are as follows:

1. Click on Transaction Security Keys option under Account Management tab.

2. Select Security Keys for the SOAP Toolkit API option as we are using SOAP toolkit API.

3. Click on Generate Key

#Note: In cybs.properties file, we have to mention the Merchant ID, Directory of the key and Filename of the transaction key in merchantID, keysDirectory and keyFilename properties respectively.

#Note: We have to first raise a ticket in Cybersource Business Center support section to enable the Recurring Billing Subscription service on the merchant ID you are using from their support center to save/ retrieve the customer profile details. Otherwise it will throw an Error code 150.

Feature: Saving/ Retrieving the customer card for future transactions.

Create and save the customer profile and card details (without charging a fee) that can be retrieved later for future transactions.

1. End Point Cybersource API URL:

“https://ics2wstest.ic3.com/commerce/1.x/transactionProcessor”

2. Creating a customer profile first requires to authorize the card used for the transaction. To validate/ authorize the customer account, following RequestMessage fields needs to be set to the corresponding values:

RequestMessage Parameters Sample Values

paySubscriptionCreateService_run true (String)

ccAuthService_run true (String)

purchaseTotals_grandTotalAmount 0.00 (String)

3. After setting the fields for authorizing the customer's card, the following RequestMessage fields needs to be set to the corresponding values:

RequestMessage Parameters Sample Values

billTo_firstName John (String)

billTo_lastName Doe (String)

billTo_city Mountain View (String)

billTo_country US (String)

billTo_email null@cybersource.com (String)

billTo_postalCode 94043 (String)

billTo_state CA (String)

billTo_street1 1295 Charleston Road (String)

card_accountNumber 4111111111111111 (String)

card_cardType 001 (String)

card_expirationMonth 12 (BigInteger)

card_expirationYear 2018 (BigInteger)

merchantID demoID (String)

merchantReferenceCode 1234 (String)

purchaseTotals_currency USD (String)

recurringSubscriptionInfo_frequency on-demand (String)

4. XML format of the request message for the above transaction call:

<requestMessage xmlns="urn:schemas-cybersource-com:transaction-data-1.92"><billTo>

<firstName>John</firstName><lastName>Doe</lastName><street1>1295 Charleston Road</street1><city>Mountain View</city><state>CA</state><postalCode>94043</postalCode><country>US</country><email>john.doe@example.com</email>

</billTo><purchaseTotals>

<currency>USD</currency></purchaseTotals><card>

<accountNumber>4111111111111111</accountNumber><expirationMonth>12</expirationMonth><expirationYear>2015</expirationYear><cardType>001</cardType>

</card><merchantID>demoID</merchantID><merchantReferenceCode>1234</merchantReferenceCode><recurringSubscriptionInfo>

<frequency>on-demand</frequency></recurringSubscriptionInfo><paySubscriptionCreateService run="true"/>

</requestMessage>

5. After setting all the required parameters, the API end point URL needs to be invoked to get the ReplyMessage from the transaction. The ReasonCode needs to be of value “100” to indicate a successful transaction.

Sample Reply for a successful transaction:

decision = ACCEPTmerchantReferenceCode = 1234paySubscriptionCreateReply_reasonCode = 100paySubscriptionCreateReply_subscriptionID = 0000562489861111purchaseTotals_currency = USDreasonCode = 100requestID = 3790672461500176056470

NOTE: The subscriptionID retrieved in the above response will be used for retrieving the customer profile for future transactions whenever the customer wants to use the same card for them.

>> Retrieving the customer card/ profile from Cybersource

1. End Point Cybersource API URL:

“https://ics2wstest.ic3.com/commerce/1.x/transactionProcessor”

2. For retrieving the customer profile from Cybersource end, following RequestMessage fields needs to be set to the corresponding values:

RequestMessage Parameters Sample Values

paySubscriptionRetrieveService_run true (String)

merchantID demoID (String)

merchantReferenceCode 1234 (String)

recurringSubscriptionInfo_subscriptionIDsubscriptionID (String) – Retrieved from the save card transaction response explained above. (0000562489861111)

3. XML format of the request message for the above transaction call:

<requestMessage xmlns="urn:schemas-cybersource-com:transaction-data-1.92"><merchantID>infodev</merchantID>

<merchantReferenceCode>1234</merchantReferenceCode><recurringSubscriptionInfo>

<subscriptionID>0000562489861111</subscriptionID></recurringSubscriptionInfo>

<paySubscriptionRetrieveService run="true"/></requestMessage>

4. After setting all the required parameters, the API end point URL needs to be invoked to get the ReplyMessage from the transaction. This ReplyMessage will contain the customer profile details which can be retrieved to make a future purchase. The ReasonCode needs to be of value “100” to indicate a successful transaction.

Sample Reply for a successful transaction:

merchantReferenceCode=1234requestID=3790689247280176056442decision=ACCEPTreasonCode=100paySubscriptionRetrieveReply_reasonCode=100

paySubscriptionRetrieveReply_cardAccountNumber=411111XXXXXX1111paySubscriptionRetrieveReply_cardExpirationMonth=12paySubscriptionRetrieveReply_cardExpirationYear=2018paySubscriptionRetrieveReply_cardType=001paySubscriptionRetrieveReply_city=Mountain ViewpaySubscriptionRetrieveReply_country=USpaySubscriptionRetrieveReply_currency=USDpaySubscriptionRetrieveReply_email=null@cybersource.compaySubscriptionRetrieveReply_firstName=JOHNpaySubscriptionRetrieveReply_frequency=on-demandpaySubscriptionRetrieveReply_lastName=DOEpaySubscriptionRetrieveReply_paymentMethod=credit cardpaySubscriptionRetrieveReply_postalCode=94043paySubscriptionRetrieveReply_state=CApaySubscriptionRetrieveReply_status=CURRENTpaySubscriptionRetrieveReply_street1=1295 Charleston Road

paySubscriptionRetrieveReply_subscriptionID=0000562489861111paySubscriptionRetrieveReply_ownerMerchantID=demoID

The above details can be used to display a saved customer card in the profile section if user wants to use this existing card for future billing and purchase.

>> Searching a transaction in Cybersource Business Center

A transaction details can be searched in Cybersource Business center using the requestID returned from the transaction call as follows:

1. Click on General Search option under Transaction Search tab. The following screen appears where you can enter the requestID to search the transaction.

2. The following transaction result screen will appear where all the related details are listed.

Feature: Payment Transaction

This feature is used to make a simple payment using a credit card against an order containing some items. Below is the sample XML for this call Request Message.

<?xml version="1.0" encoding="utf-8"?><requestMessage xmlns="_NSURI_">

<merchantReferenceCode>1234</merchantReferenceCode><billTo>

<state>CA</state><postalCode>94043</postalCode><country>US</country><phoneNumber>650-965-6000</phoneNumber><email>nobody@cybersource.com</email><ipAddress>10.7.7.7</ipAddress>

</billTo><shipTo>

<firstName>Jane</firstName><lastName>Doe</lastName><street1>100 Elm Street</street1><city>San Mateo</city><state>CA</state><postalCode>94401</postalCode><country>US</country>

</shipTo><item id="0">

<unitPrice>12.34</unitPrice></item><item id="1">

<unitPrice>56.78</unitPrice></item><purchaseTotals>

<currency>USD</currency></purchaseTotals><card>

<accountNumber>4111111111111111</accountNumber><expirationMonth>12</expirationMonth><expirationYear>2020</expirationYear>

</card><ccAuthService run="true"></ccAuthService>

</requestMessage>

Feature: On Demand Transaction

This feature is used to charge an already subscribed credit card against an amount on demand.

To request an on-demand sale transaction:

Step 1 Set the ccAuthService_run service field to true.Step 2 Set the ccCaptureService_run service field to true.Step 3 Include the following fields in the request: merchantID merchantReferenceCode purchaseTotals_currency purchaseTotals_grandTotalAmount recurringSubscriptionInfo_subscriptionID

Feature: Converting a Transaction to a Customer Profile

This feature is used to subscribe a credit card on Cybersource along with an ongoing transaction. When you create a customer profile from an existing transaction, the account is already validated.

To convert a transaction to a customer profile:

Step 1 Set the paySubscriptionCreateService_run service field to true.Step 2 Include the following fields in the request:merchantIDmerchantReferenceCoderecurringSubscriptionInfo_frequency—set to “on-demand”.paySubscriptionCreateService_paymentRequestID—include the requestID value returned from the original transaction request.

-------------------------------------------------------------------------------------------------------------------------------------------

References:

1. Payment Tokenization (Using the Simple Order API for CyberSource Essentials)http://apps.cybersource.com/library/documentation/sbc/SB_Payment_Tokenization/SO_API/SB_Payment_Tokenization_SO_API.pdf

2. CyberSource SOAP Toolkits for Web Services (Developer Guide)http://apps.cybersource.com/library/documentation/dev_guides/SOAP_Toolkits/SOAP_toolkits.pdf