Integration Guide
This will guide you through the whole integration process with Cybersource’s Secure Acceptance Hosted
Checkout. This will abstract the process of worrying to store sensitive payment information on your
servers.
This requires average scripting skills and you can use any Programming/Scripting language. This can be
integrated with Websites or Mobile apps. We recommend you to create your own security script or use
the one provided in Abyssinia Bank portal rather than using the one provided in examples. You can use
EBC to review and manage orders.
Requirements
On your application end you are required to provide Cart or some script to initiate transaction with
Cybersource servers. Make sure SSL is installed/configured on your Host/Servers.
Setting Up Profile
After you get Email to set up account, first you’ll need to setup Profile. On the side navigation head to
Payment Configuration > Secure Acceptance Settings.
Select Inactive Profiles to get list of the profiles prepared for you.
Choose SAHostedCheckout
On right side click on the pencil icon to start editing the profile
Editing profile consists of Several tabs. Make sure to save settings in each tab before moving to the other
and save the whole Profile at the end.
The first tab is Profile Information. Basic information is filled up here. You can Name your Profile anything
and put a description. You can have multiple profiles, say for different sites.
Make sure Decision Manager, Verbose Data and Generate Device Fingerprint. If you want to generate
and handle your own fingerprint you can override this setting on your script.
Before moving to the next tab make sure to save this. This is required for all tabs too.
On the Payment Settings tab make sure the Fails AVS check and Fails CVN check are active. You’ll migrate
to 3DS 2.0 once your cardinal is configured.
Click on the settings icon next to Visa and MasterCard and make sure everything is ticked.
Now move to the security Tab and click on the + icon to generate new key. Keep these keys to yourself
even if it’s on test Environment.
Name your key and click on Create.
Cybersource will generate Access Key and Security Key. You can copy this to your script or Download
them. The access key will be embedded on the Front-end i.e. HTML or Form While security key should be
kept hidden in your backend.
KEY Here
Now Move to the Payment Form Tab. These Tab formats you the Payment page. You can choose between
single page/Multi-step payment form. You can check Billing Information and Shipping Information page.
If you don’t check these here, you have to prepare form on your page and then send the data. If you opt
to choose to prepare your own form, you’ll have to comply with the standard provided by Cybersource.
We will go through these standards in the next chapter.
Move to the Notifications. Here you can put in POST URL, POST Email. If you tick Email Receipt to
Customer will automatically get email after transaction.
Move to the next tab Customer Response. The Transaction Response lets you choose between Hosted
by Cybersource or Hosted by You. if you choose Hosted by Cybersource, Cybersource will view the
Successful or declined page. If you choose to Host it, you’ll be prompted to put in Link to your response
page. Custom Cancel Response Page stands for if you want to host the page if the Customer cancels
midway the payment process.
then put in Custom Redirect After Checkout, this is where you catch transaction response data from
Cybersource. This data is important to your application, especially if you there is script running after
payment. We’ll go through the response data in the next chapters. We recommend you to Provide
endpoint designed specifically to handle this response.
After configuring all these go to the top right corner and Activate the profile.
Finally after these steps you can see your profile in the active profiles list.
Setting up the Application
Data’s that you send to Cybersource servers are classified as Signed and unsigned. In this use case all the
data you send should be signed. Collect data from the user, sign it with security Script then send the data’s
along with signature. We’ve listed the fields with description below. All these fields are sent by POST.
access key - Obtained while generating keys. Check previous chapter.
profile_id - ID of the profile you’re using. You can find it at Payment Configuration > Secure Acceptance
Settings then view the profile you’re using.
transction_uuid - Unique Transaction Identifier. Generate this at your application. You can use timestamp
while you’re testing.
signed_field_names - List of all fields that you signed. Make sure that all fields are here, separated by
comma.
Signed_date_time - yyyy-MM-dd HH:mm z – Make sure to use this format.
Locale - Localization information. Pass en for most use cases.
transaction type - this value must be sale.
reference_number - unique. Better to use UUID.
Amount - amount that you’re charging. Integer/Decimal.
Currency - currency that you’re charging in. USD/ETB/GBP/EUR
Incase you want to accept billing information at your end, pass in the following information
bill_to_forename - First Name
bill_to_surname - Last Name
bill_to_email - Email
bill_to_phone - Phone
bill_to_address_line1 - Address
bill_to_address_city - City
bill_to_address_state - If not US or Canada don't submit state, If US or CA submit state code, Usually 2
letter Word
bill_to_address_country - Submit ISO standard country code. i.e. ET, US
bill_to_address_postal_code – Postal code of the area. Pass 1000 if postal code isn’t available.
If your account is assigned to Merchant Defined Fields (MDD), you have to pass those here with the
signed data fields as well. You can be assigned to different size of MDD fields. Replace the # with number
and pass in the data there.
Merchant_defined_data# - fill in the # with number and attach proper value to it.
Sign these data with security script and then prepare a signature. Pass in the Signature with all the original
values and hit the proper endpoint https://testsecureacceptance.cybersource.com/pay.
N.B - You can check get sample security scripts on ecommerce.bankofabyssinia.com. We recommend you
understand the process and build your own security script with proper Object Oriented Programming
Paradigm. We will shortly release official libraries with different programming languages on our portal.
Response Data
Response data from the Cybersource will be sent to your endpoint provided on the profile setup. The
data is POST request. You can parse that data to JSON, XML or any other format you want and use it as
your application need.
You can monitor transactions on EBC /Enterprise Business Center/. You can debug most problems from
there and if you need any additional help contact Support at our portal ecommerce.bankofabyssinia.com.
Bank of Abyssinia