This blog provides a comprehensive guide on how to integrate Visual Builder (VB) with payment gateway to enable seamless payment processing. It aims to help readers understand the necessary steps to configure the payment gateway in VB, set up the payment pages, test the integrations, and go live. The goal is to help businesses enhance their payment processing capabilities by leveraging the powerful tools and features of VB and payment gateway. This blog will discuss the various aspects involved considering CyberSource as a payment gateway, but the architecture would be similar if integrating with other payment gateways.
CyberSource Payment Gateway Overview
CyberSource payment gateway is a payment processing solution provided by CyberSource Corporation. It is a secure and reliable payment gateway that enables businesses to accept payments from customers worldwide. With CyberSource payment gateway, you get access to a variety of payment options, including credit cards, debit cards, and alternative payment methods.
It also comes with a range of features that can help you streamline your payment processing operations. For instance, you get access to Fraud Detection, which can help you prevent fraudulent transactions. You also get Global Payment Processing, which means you can accept payments in multiple currencies from customers around the world.
In addition, CyberSource payment gateway provides Reporting and Analytics, which can help you gain insights into your payment processing performance, and if you need to integrate CyberSource payment gateway with your existing systems, it offers a range of integration options, including APIs, SDKs, and plugins.
Oracle VB and CyberSource Secure Acceptance Hosted Checkout Integration
This section details the steps required to integrate VB application with CyberSource payment gateway using secure acceptance hosted checkout method and JSP SDK.
Architecture
This involves a multi-tier architecture with different components working together to enable payment processing. Here is an overview of the architecture:
- Client tier – This is the front-end of the application that runs on the customer's web browser. It includes the VB application that provides the user interface for payment processing.
- Servlet tier – This is the middle tier of the application that runs on the OIC compute + OCI load balancer. Load balancer is on public subnet and is authenticated using oAuth. Apache tomcat is hosted in the Private subnet and includes the servlet that acts as a bridge between the VB application and the CyberSource payment gateway. The request servlet receives the payment request from the VB application, passes it to the CyberSource payment gateway for processing, and response servlet return the CyberSource response to the VB application.
- Runtime exceptions if any during execution of payment process is handled via exception handling block that redirects back to VB screen with error code and message.
- CyberSource Payment Gateway Tier – CyberSource provides the payment interface based on the request received from the servlet and allows end users to process the payment. Customer response engine returns the payment response to the servlet. Creation of a CyberSource account and configuration of the settings are discussed in the subsequent sections.
Transaction flow
Step 1: Create a Visual Builder Application
- Create a VB application with form fields that are necessary to process the payment like amount, currency, payment status, payment date, payment acknowledgment number etc.
- Add a Pay button on form that will invoke the servlet URL to process the payment. This custom servlet application will integrate VB with CyberSource.
- On click of a pay button first create a transaction in the DB with Payment status as Initiated and redirect to servlet URL using the open URL in action chain. Pass the encoded unique transaction ID in the servlet URL. This ID will be further used inside servlet to get the required payment fields from DB and will be passed on to the CyberSource.
Step 2: Configure a CyberSource account
- Contact CyberSource Customer Support to enable your account for Secure Acceptance and get the Merchant Id.
- Login to CyberSource business portal and navigate to Payment Configuration > Secure Acceptance Settings to create a new profile.
- General settings – Profile Information (Name, Description), Integration Methods and Contact Information. Note, keep integration method as Hosted Checkout.
- Payment Settings – This tab allows you to enable or disable the card types, currencies that should be accepted while payment transactions.
Note: Enable payer authentication if OTP authentication is required before payment transaction.
- Security – You must create a security key before you can activate a profile. The security script signs the request fields using the secret key and the HMAC SHA256 algorithm. To verify data, the security script generates a signature to compare with the signature returned from the Secure Acceptance server.
Note: Download and save the Access Key and Secret Key. These keys will be used in the custom servlet application that is hosted in OCI compute to authenticate with CyberSource. Store the keys in OCI vault and retrieve it in servlet.
- Payment Form – The payment form is the customer's checkout experience. It consists of either a series of pages or as a single checkout page in which the customer enters or reviews information before submitting a transaction. Select the fields that you want displayed on the single checkout page or on each page of the multi-step checkout process: billing, shipping, payment, and order review.
- Notifications – Secure Acceptance sends merchant and customer notifications in response to transactions. You can receive a merchant notification by email or as an HTTPS POST to a URL for each transaction processed. Both notifications contain the same transaction result data.
- Customer Response – You must configure the customer response page before you can activate a profile. You can choose to have a transaction response page displayed to the customer at the end of the checkout process, and a cancel response page displayed during the checkout process. Enter a URL for your own customer response page that hosted in OCI compute instance or use the CyberSource hosted response pages. Depending upon the transaction result, the CyberSource hosted response pages are Accept, Decline, or Error. Review declined orders as soon as possible because you might be able to correct problems related to address or card verification, or you might be able to obtain a verbal authorization. You can also choose to display a web page to the customer after the checkout process is completed.
Step 3: Activate CyberSource Profile
You must complete the required settings described in each of above sections before you can activate a profile. To activate a profile, navigate to Payment Configuration > Secure Acceptance Settings and click on Promote Profile icon.
Once the profile is activated, save the profile id. Again, this profile id is required in the Servlet code for communication with CyberSource.
Step 4: Download CyberSource SDK’s
Secure Acceptance can support any dynamic scripting language that supports HMAC256 hashing algorithms. Download the SDK from the website https://developer.cybersource.com/
Transaction Process Using JSP:
- Payment_form.jsp file – represents the customer's product selection on a website. Enter your ACCESS_KEY and PROFILE_ID into their respective fields. POST the fields to your server to sign and create the signature. All the fields must be included in the signed_field_names field as a CSV list.
- Security.jsp file – security algorithm signs field and creates a signature using the signed_field_names field. Enter your security key in the SECRET_KEY field. Modify the security script to include the Secret Key that you generated in Security Keys.
- Payment_confirmation.jsp file – represents the customer order review page on a website before the customer makes a payment. POST transaction to the Secure Acceptance endpoint and render the Hosted Checkout Integration
Step 5: Servlet Code Configuration
- Create a maven servlet application using IDE like eclipse, NetBeans etc.
- Retrieve the transaction ID from the incoming request (VB) using the HttpServletRequest object. This is typically done using the getParameter() method.
- Decode the transaction ID received from VB, create ORDS call to fetch the record from DB. ORDS call can be executed using HttpURLConnection.
Note: Store ORDS authentication keys and password in OCI vault. Use OCI vault SDKs to retrieve it in servlet to generate authentication token.
URL url = new URL(<ENTER URL HERE>);
HttpURLConnection conn = (HttpURLConnection) url.openConnection();// Set the request header
//Generate token using ORDS oAuth API and get keys/credentials from OCI vault
conn.setRequestProperty("Authorization", "Bearer " + <ENTER TOKEN HERE>);
if (conn.getResponseCode() == 200) {// Read the response
BufferedReader rd = new BufferedReader(new InputStreamReader(conn.getInputStream()));
StringBuilder sb = new StringBuilder();
String line;
while ((line = rd.readLine()) != null) {
sb.append(line);
}
rd.close();
String response = sb.toString();
JsonObject coderollsJsonObject = gson.fromJson(response, JsonObject.class);
- Store the ORDS response in a session variable using request.getSession().setAttribute().
- Include the CyberSource SDK in the servlet application – payment_form.jsp, payment_confirmation.jsp, security.jsp etc.
- Assuming that the payment details are retrieved successfully, the servlet will then construct a payment request using the payment gateway's API. This involves creating a connection to the payment gateway, specifying the payment amount, currency, and any other relevant details, and submitting the payment request using the appropriate API method. Redirect the servlet to a payment_form.jsp using request.getRequestDispatcher("/payment_form.jsp")
- Get the ORDS response along with CyberSource Access key and Profile Id inside the Payment_form.jsp and on load redirect it to payment_confirmation.jsp.
Note: Store CyberSource keys in OCI vault. Use OCI vault SDKs to retrieve it in servlet to authenticate and process payment.
<html>
<head>
<script type="text/javascript" src="jquery-1.7.min.js"></script>
</head>
<body onload="javascript: document.PaymentForm.submit();">
<%
String access_key = (String) request.getSession().getAttribute("access_key");
String profile_id = (String) request.getSession().getAttribute("profile_id");
…
…
…
String transaction_number = (String) request.getSession().getAttribute("transaction_number");
Number amount = (Number) request.getSession().getAttribute("amount");
String currency = (String) request.getSession().getAttribute("currency");
%>
<div style="display: none;">
<form id="payment_form" action="payment_confirmation.jsp" name="PaymentForm" method="post">
<input type="hidden" name="access_key" value=<%=access_key%>>
<input type="hidden" name="profile_id" value=<%=profile_id%>>
<input type="hidden" name="transaction_uuid"
value="<%=UUID.randomUUID()%>"> <input type="hidden"
name="signed_field_names" value="access_key,profile_id,transaction_uuid,signed_field_names,unsigned_field_names,signed_date_time,locale,transaction_type,reference_number,amount,currency">
…
…
…
<span>amount:</span><input type="text" name="amount" size="25"
value=<%=amount%>><br /> <span>currency:</span><input
type="text" name="currency" size="25" value=<%=currency%>><br />
</div>
</fieldset>
<script type="text/javascript" src="payment_form.js"></script>
</form>
</div>
<div class="itembox" id="step4box" align="center">
<h4>Please wait while we redirect you to the payment page…</h4>
</div>
</body>
</html>
- Payment_confirmation.jsp will redirect the payment request to cybersource.com/pay.
<html>
<head>
<title>Secure Acceptance – Payment Form Example</title>
<link rel="stylesheet" type="text/css" href="payment.css" />
</head>
<body onload="javascript: document.PaymentConfirm.submit();">
<%
String redirectURL = "/receipt.jsp";
String cyberSourceURL = <ENTER URL HERE>;
%>
<div style="display: none;">
<form id="payment_confirmation" action=<%=cyberSourceURL %> name="PaymentConfirm" method="post" />
<%
request.setCharacterEncoding("UTF-8");
HashMap params = new HashMap();
Enumeration paramsEnum = request.getParameterNames();
while (paramsEnum.hasMoreElements()) {
String paramName = (String) paramsEnum.nextElement();
String paramValue = request.getParameter(paramName);
params.put(paramName, paramValue);
}
%>
<fieldset id="confirmation">
<legend>Review Payment Details</legend>
<div>
<%
Iterator paramsIterator = params.entrySet().iterator();
while (paramsIterator.hasNext()) {
Map.Entry param = (Map.Entry) paramsIterator.next();
%>
<div>
<span class="fieldName"><%=param.getKey()%>:</span><span
class="fieldValue"><%=param.getValue()%></span>
</div>
<%
}
%>
</div>
</fieldset>
<%
paramsIterator = params.entrySet().iterator();
while (paramsIterator.hasNext()) {
Map.Entry param = (Map.Entry) paramsIterator.next();
}
%>
</form>
<form action=<%=redirectURL%> method="post" name="redirectForm"
id="network_online_payment"></form>
</div>
<div class="itembox" id="step4box" align="center">
<h4>Please wait while we redirect you to the payment page…</h4>
</div>
</body>
</html>
- Now, create two custom jsp’s –
1. Receipt.jsp – where CyberSource will send the response. The URL of this JSP needs to be configured in CyberSource portal. Steps explained in section ‘Step 2: Configure a CyberSource account’.
Update the CyberSource payment response in DB based on transaction id and redirect to VB app from this URL once the response is captured from CyberSource.
<%
String redirectURL = <ENTER URL HERE>;
%>
<html>
<head>
<title>Secure Acceptance – Payment Form Example</title>
<link rel="stylesheet" type="text/css" href="payment.css" />
</head>
<body onload="javascript: document.redirectForm.submit();">
<fieldset id="response" style="display: none;">
<legend>Receipt</legend>
<div style="display: none;">
<form id="receipt">
<%
HashMap params = new HashMap();
Enumeration paramsEnum = request.getParameterNames();
while (paramsEnum.hasMoreElements()) {
String paramName = (String) paramsEnum.nextElement();
String paramValue = request.getParameter(paramName);
params.put(paramName, paramValue);
}
session.setAttribute("reason_code", params.get("reason_code"));
session.setAttribute("decision", params.get("decision"));
…
…
…
session.setAttribute("trans_id", params.get("req_reference_number"));
session.setAttribute("signed_date_time", params.get("signed_date_time"));
%>
</form>
<form action=<%=redirectURL%> method="post" name="redirectForm" id="network_online_payment"></form>
</div>
</fieldset>
<div class="itembox" id="step4box" align="center">
<h4>Please wait while we redirect you to the application…</h4>
</div>
</body>
</html>
2. Error.jsp – Redirect servlet exceptions to this JSP
<body>
<%
String redirectURL = <ENTER URL HERE>;
%>
<form action=<%=redirectURL%> name="error" id="error" method="post">
<div class="itembox" id="step4box" align="center">
<h4>There is an error while processing the payment…</h4>
<div id="words" class="gothbold">
Please wait while we redirect you to the web site.
</div>
<a class="redirect" href="javascript:void(0)"
title="Proceed to Website" onClick="document.error.submit();"><span>If
you aren't redirected in 5 seconds click here</span></a><br />
</div>
<script type="text/javascript">
window.onload = function() {
window.setTimeout(document.error.submit
.bind(document.error), 5000);
};
</script>
</form>
</body>
- Create a .war file of the servlet code and deploy it on application server like Apache Tomcat. Get the Servlet URL and configure it in VB and CyberSource portal.
Conclusion
Integrating Oracle Visual Builder with CyberSource payment gateway can help businesses streamline their payment processing operations. By following the steps outlined in this blog post, you can easily set up the integration and start accepting payments in no time.