CybersourceAPIintegrationdocumentation

ThisdocumentwillexplainhowwecanintegrateCybersourceAPIintoourapplicationbysettingtherequired
RequestparametersandinvokingtheendpointurlformakingaSOAPcalltoCybersourceAPItoperformdifferent
operationslikePaymenttransactions;Saving/Retrievingcustomercreditcarddetails;ondemandtransactionand
convertinganexistingtransactiontocustomerprofile.
Packages&JARSused
We are using Apache Axis and WSS4J toolkit for constructing and making the SOAP web service call to
Cybersource.
PackagesUsed
Packagesused

Description

ApacheAxis1.4

SOAPtoolkit
Downloadandunzipthelatestpackagefromhttp://ws.apache.org/axis

ApacheWSS4J1.5.1

WSSecuritypackage
Downloadandunzipthelatestpackagefromhttp://ws.apache.org/wss4j

activation.jar

JDK JavaBeans Activation Framework addon that you can download from
http://www.oracle.com/technetwork/java/jaf11139815.html

Apache XML Security XMLsecuritypackage

1.4.0
Downloadthelatestpackagefromhttp://santuario.apache.org/download.htmlandextract
xmlsecN.N.N.jar
JARSUsed
Packages

JARS

ApacheAxis

axis.jar
commonsdiscovery0.2.jar
commonslogging1.0.4.jar
jaxrpc.jar
log4j1.2.8.jar
saaj.jar
wsdl4j1.5.1.jar

ApacheWSS4J

wss4j1.5.1.jar
GeneratingandBuildingtheStubs.

WehavetogenerateStubsfromthewsdlfiledownloadedfromtheCybersource.Thestepsareasfollows:
Step1.DownloadtheCybersourceSamplecodefrom:
http://www.cybersource.com/support_center/implementation/downloads/soap_api/sample_files/sample_axis_wss4j.
zip
#FiledescriptioninSamplecode:
a.Sample.java:samplefile,whichprovidesthecodetoprocessyourtransactions.Thefilecontainscommentsand
asamplecardauthorization.
b.SamplePWCallback.java:samplePasswordCallbackHandler,whichprovidesthepasswordtoWSS4J.

c.SampleDeploy.wsdd:sampledeploymentdescriptorfileusedbyWSS4J.
Step 2. From a command prompt, go to the directory where you downloaded the CyberSource sample code
Sample.java.
Step3.Togeneratethestubs,executethiscommandwithoutlinebreaks:
java

org.apache.axis.wsdl.WSDL2Java

com.cybersource.stub
https://ics2wsa.ic3.com/commerce/1.x/transactionProcessor/CyberSourceTransaction_1.123.wsdl
Here,com.cybersource.stubisthepackagenamethatwillbeusedforthegeneratedclassesandthelatestwsdl
versionislocatedat:
https://ics2wsa.ic3.com/commerce/1.x/transactionProcessor/CyberSourceTransaction_1.123.wsdl
Step4.Tocompilethesourcecode,executethiscommand:
javaccom/cybersource/stub/*.java
Step5.Createajarfilebyusingthecompiledclasses:
jarcfcybersource.jarcom/cybersource/stub/*.class
Step6.Addthenewlycreatedcybersource.jartoyourclasspath.
#Note:TheJAVAclasses(stub)formwsdlcanbegeneratedbyfollowingthisstep
RightClickonanyProject>CreateNewOther>WebServices>WebServiceClient>Thenpastethewsdlurl(or
location)inServiceDefinition>Next>Finish
BuildingtheSampleandTestingtheClient.
Tobuildthesampleandtestyourclient,modifythevariablesinthesamplefiles,andruntheapplication.
Step1InSample.java,modifythevaluesofMERCHANT_ID.
Step2InSamplePWCallback.java,modifythevalueofTRANSACTION_KEY.
Step3Compilethesamplesasfollows:javacSample.javaSamplePWCallback.java
Step4Runthesampleasfollows:javaDaxis.ClientConfigFile=SampleDeploy.wsddSample
Thereplyfilecontainstherequestresultandallreturnedfields.Whentestingtheclientisfinished,writethecodeto
usetheclientapplication.
#Note:TheMERCHANT_ID&TRANSACTION_KEYareobtainedthroughtheCybersourceBusinessCenter
accountwhichisexplainedinthebelowsection.
CybersourceTestBusinessCentersteps:
Url:https://ebctest.cybersource.com/ebctest/login/
WeneedtocreateaCybersourcemerchantaccounttotestoutourtransactionsandretrievea MerchantIDand
TransactionKey.AftercreatinganaccountandobtainingtheMerchantID(assignedautomaticallytoanewly
createdaccount),thestepstocreatetheTransactionKeyareasfollows:

1. ClickonTransactionSecurityKeysoptionunderAccountManagementtab.

2. SelectSecurityKeysfortheSOAPToolkitAPIoptionasweareusingSOAPtoolkitAPI.

3. ClickonGenerateKey

#Note: Incybs.propertiesfile,wehavetomentiontheMerchantID,DirectoryofthekeyandFilenameofthe
transactionkeyinmerchantID,keysDirectoryandkeyFilenamepropertiesrespectively.
#Note: WehavetofirstraiseaticketinCybersourceBusinessCentersupportsectiontoenabletheRecurring
Billing Subscriptionservice on themerchant IDyouare usingfrom their support center tosave/ retrieve the
customerprofiledetails.OtherwiseitwillthrowanErrorcode150.
Feature:Saving/Retrievingthecustomercardforfuturetransactions.
Createandsavethecustomerprofileandcarddetails(withoutchargingafee)thatcanberetrievedlaterforfuture
transactions.
1.EndPointCybersourceAPIURL:
https://ics2wstest.ic3.com/commerce/1.x/transactionProcessor
2.Creatingacustomerprofilefirstrequirestoauthorizethecardusedforthetransaction.Tovalidate/authorizethe
customeraccount,followingRequestMessagefieldsneedstobesettothecorrespondingvalues:
RequestMessageParameters

SampleValues

paySubscriptionCreateService_run

true(String)

ccAuthService_run

true(String)

purchaseTotals_grandTotalAmount

0.00(String)

3.Aftersettingthefieldsforauthorizingthecustomer'scard,thefollowingRequestMessagefieldsneedstobeset
tothecorrespondingvalues:
RequestMessageParameters

SampleValues

billTo_firstName

John
(String)

billTo_lastName

Doe(String)

billTo_city

MountainView(String)

billTo_country

US(String)

billTo_email

null@cybersource.com(String)

billTo_postalCode

94043(String)

billTo_state

CA(String)

billTo_street1

1295CharlestonRoad(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

ondemand(String)

4.XMLformatoftherequestmessagefortheabovetransactioncall:
<requestMessagexmlns="urn:schemascybersourcecom:transactiondata1.92">
<billTo>
<firstName>John</firstName>
<lastName>Doe</lastName>
<street1>1295CharlestonRoad</street1>
<city>MountainView</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>ondemand</frequency>
</recurringSubscriptionInfo>
<paySubscriptionCreateServicerun="true"/>
</requestMessage>
5.Aftersettingalltherequiredparameters,theAPIendpointURLneedstobeinvokedtogettheReplyMessage
fromthetransaction.TheReasonCodeneedstobeofvalue100toindicateasuccessfultransaction.
SampleReplyforasuccessfultransaction:
decision=ACCEPT
merchantReferenceCode=1234
paySubscriptionCreateReply_reasonCode=100
paySubscriptionCreateReply_subscriptionID=0000562489861111
purchaseTotals_currency=USD
reasonCode=100
requestID=3790672461500176056470
NOTE:The subscriptionID retrievedintheaboveresponsewillbeusedforretrievingthecustomerprofilefor
futuretransactionswheneverthecustomerwantstousethesamecardforthem.

>>Retrievingthecustomercard/profilefromCybersource
1.EndPointCybersourceAPIURL:
https://ics2wstest.ic3.com/commerce/1.x/transactionProcessor
2.ForretrievingthecustomerprofilefromCybersourceend,followingRequestMessagefieldsneedstobesetto
thecorrespondingvalues:
RequestMessageParameters

SampleValues

paySubscriptionRetrieveService_run

true(String)

merchantID

demoID(String)

merchantReferenceCode

1234(String)

recurringSubscriptionInfo_subscriptionID

subscriptionID (String)Retrievedfromthe
save card transaction response explained
above.(0000562489861111)

3.XMLformatoftherequestmessagefortheabovetransactioncall:
<requestMessagexmlns="urn:schemascybersourcecom:transactiondata1.92">
<merchantID>infodev</merchantID>
<merchantReferenceCode>1234</merchantReferenceCode>
<recurringSubscriptionInfo>
<subscriptionID>0000562489861111</subscriptionID>
</recurringSubscriptionInfo>
<paySubscriptionRetrieveServicerun="true"/>
</requestMessage>
4.Aftersettingalltherequiredparameters,theAPIendpointURLneedstobeinvokedtogettheReplyMessage
fromthetransaction.ThisReplyMessagewillcontainthecustomerprofiledetailswhichcanberetrievedtomakea
futurepurchase.TheReasonCodeneedstobeofvalue100toindicateasuccessfultransaction.
SampleReplyforasuccessfultransaction:
merchantReferenceCode=1234
requestID=3790689247280176056442
decision=ACCEPT
reasonCode=100
paySubscriptionRetrieveReply_reasonCode=100
paySubscriptionRetrieveReply_cardAccountNumber=411111XXXXXX1111
paySubscriptionRetrieveReply_cardExpirationMonth=12
paySubscriptionRetrieveReply_cardExpirationYear=2018
paySubscriptionRetrieveReply_cardType=001
paySubscriptionRetrieveReply_city=MountainView
paySubscriptionRetrieveReply_country=US
paySubscriptionRetrieveReply_currency=USD
paySubscriptionRetrieveReply_email=null@cybersource.com

paySubscriptionRetrieveReply_firstName=JOHN
paySubscriptionRetrieveReply_frequency=ondemand
paySubscriptionRetrieveReply_lastName=DOE
paySubscriptionRetrieveReply_paymentMethod=creditcard
paySubscriptionRetrieveReply_postalCode=94043
paySubscriptionRetrieveReply_state=CA
paySubscriptionRetrieveReply_status=CURRENT
paySubscriptionRetrieveReply_street1=1295CharlestonRoad
paySubscriptionRetrieveReply_subscriptionID=0000562489861111
paySubscriptionRetrieveReply_ownerMerchantID=demoID
Theabovedetailscanbeusedtodisplayasavedcustomercardintheprofilesectionifuserwantstousethis
existingcardforfuturebillingandpurchase.
>>SearchingatransactioninCybersourceBusinessCenter
A transaction details can be searched in Cybersource Business center using the requestID returned from the
transactioncallasfollows:
1.ClickonGeneralSearchoptionunderTransactionSearchtab.Thefollowingscreenappearswhereyoucan
entertherequestIDtosearchthetransaction.

2.Thefollowingtransactionresultscreenwillappearwherealltherelateddetailsarelisted.

Feature:PaymentTransaction
Thisfeatureisusedtomakeasimplepaymentusingacreditcardagainstanordercontainingsomeitems.Belowis
thesampleXMLforthiscallRequestMessage.
<?xmlversion="1.0"encoding="utf8"?>
<requestMessagexmlns="_NSURI_">
<merchantReferenceCode>1234</merchantReferenceCode>
<billTo>
<state>CA</state>
<postalCode>94043</postalCode>
<country>US</country>
<phoneNumber>6509656000</phoneNumber>
<email>nobody@cybersource.com</email>
<ipAddress>10.7.7.7</ipAddress>
</billTo>
<shipTo>
<firstName>Jane</firstName>
<lastName>Doe</lastName>
<street1>100ElmStreet</street1>
<city>SanMateo</city>
<state>CA</state>
<postalCode>94401</postalCode>
<country>US</country>
</shipTo>
<itemid="0">
<unitPrice>12.34</unitPrice>
</item>
<itemid="1">
<unitPrice>56.78</unitPrice>
</item>
<purchaseTotals>
<currency>USD</currency>
</purchaseTotals>
<card>
<accountNumber>4111111111111111</accountNumber>
<expirationMonth>12</expirationMonth>
<expirationYear>2020</expirationYear>
</card>
<ccAuthServicerun="true">
</ccAuthService>
</requestMessage>

Feature:OnDemandTransaction
Thisfeatureisusedtochargeanalreadysubscribedcreditcardagainstanamountondemand.
Torequestanondemandsaletransaction:
Step1SettheccAuthService_runservicefieldtotrue.
Step2SettheccCaptureService_runservicefieldtotrue.
Step3Includethefollowingfieldsintherequest:
merchantID
merchantReferenceCode

purchaseTotals_currency
purchaseTotals_grandTotalAmount
recurringSubscriptionInfo_subscriptionID
Feature:ConvertingaTransactiontoaCustomerProfile
ThisfeatureisusedtosubscribeacreditcardonCybersourcealongwithanongoingtransaction.Whenyoucreatea
customerprofilefromanexistingtransaction,theaccountisalreadyvalidated.
Toconvertatransactiontoacustomerprofile:
Step1SetthepaySubscriptionCreateService_runservicefieldtotrue.
Step2Includethefollowingfieldsintherequest:
merchantID
merchantReferenceCode
recurringSubscriptionInfo_frequencysettoondemand.
paySubscriptionCreateService_paymentRequestIDinclude the requestID value returned from the original
transactionrequest.

References:
1.PaymentTokenization(UsingtheSimpleOrderAPIforCyberSourceEssentials)
http://apps.cybersource.com/library/documentation/sbc/SB_Payment_Tokenization/SO_API/SB_Payment_Tokeniz
ation_SO_API.pdf
2.CyberSourceSOAPToolkitsforWebServices(DeveloperGuide)
http://apps.cybersource.com/library/documentation/dev_guides/SOAP_Toolkits/SOAP_toolkits.pdf