Cybersource API documentation

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

This document will explain the required Request parameters and the end point url for making a SOAP call to Cybersource API to create and save the customer profile and card details (without charging a fee) that can be retrieved later for future transactions.

>> 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

>> Creating the STUB from cybersource wsdl file.

We have to create the stub from the Cybersource wsdl file which we downloaded from the below url. The wsdl file is “CyberSourceTransaction_1.121.wsdl”.

The wsdl can be downloaded from the url: https://ics2wsa.ic3.com/commerce/1.x/transactionProcessor/CyberSourceTransaction_1.123.wsdl

#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

#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.

>> Saving the customer card/ profile on Cybersource

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. 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.

5. 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>

>> 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.

3. 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 RoadpaySubscriptionRetrieveReply_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.