Payment processing is one of the most important areas of any e-commerce platform, it’s even considered one of the backbones of these platforms. Knowing your way around this area is a critical skill that every digital commerce developer should have in their wheelhouse. In this webinar, I share my expierence on payment gateways and demonstrate how to integrate Salesforce Commerce Cloud with Cybersource, an ecommerce credit card payment management solution. Please find the transcript of the video below 🔽

Let’s put a stake in the ground and start by addressing the elephant in the room, what is a payment gateway? many of you might not really know what what payment gateways are.. so here goes the definition.. Payment gateways are services that authorize credit card processing.. that’s it. but what does that mean exactly, right? In a nutshell payment gateways are responsible for authorizing payments on the site. That’s it.. Payment gateways have one and only one critical job and that is to allow users to pay online.

There are a lot of payment gateways out there, with different features and different limitations. For example, we’ve got Stripe, Square, Skrill, and there’s also Adyen now trending. Some of you might know some, some might know all, and some might know none of these. So the one million dollar question would be, what’s so special about Cybersource then?

To answers to answer this question we need to make a little comparison. I know Cybersource integration is very time consuming - and trust me many developers in ITG (my current employer) have faced this issue a lot - and other payment gateways have faster and simpler integrations with ecommerce sites. Other gateways heavily lack at detecting fraudulent activities. This is a very important feature and I can’t really stress enough how much this feature is important, especially for major retailers.. if you think about it, major retailers uh get a high load of orders not even daily but at an hourly basis. So and to elaborate a bit on this (because this is a very important point), sometimes some people would try to use a stolen card, or might use a low ranked card and by low ranked cards I mean cards that have low credit score, or try to impersonate other people. That’s where the fraud detection of Cybersource kicks in. This is one of Cybersource’s finest features to be honest with you, they actually make ads about this feature.

Cybersource detection uses certain patterns and algorithms to flag high risk transactions and cards. The other important deciding factor in why cybersource is one of the best payment gateways out there is the parent company. Cybersource’s parent company is Visa. Visa has acquired Cybersource in 2010 I guess, not sure but I believe 2010, and it has always been, and I mean Visa, a leading company in the banking sector. So all the new updates get pushed to Cybersource faster than any other payment gateway. So that’s why major retailers go with Cybersource. and by the way, Cybersource is a legacy solution.. it has always been there for a very long time. So, familiarity is another reason why major retailers pick Cybersource.

Okay, so enough talking about the concepts let’s hop to the technical side of the integration. It’s not going to be a dive deep tutorial per se, it’s going to be a high level integration.

Once you decide to start the integration process. Cybersource will provide you with the out of the box plugin. The out of the box plugin is a separate cartridge that contains all the necessary POJOs (Plain Old Java Objects), DTOs(Data Transfer Objects), logic, service definition files (WSDLs) and jobs. Then you might think what do I need to do then if everything is provided?! what’s my job?! Your job is to configure, customize, and connect this toolbox that you have with the code base of your client. Easy peasy lemon squeezy you might think, but not so much. Let me tell you why.. Cybersource is a HUGE solution and I can’t really demonstrate how huge the solution is.. Some projects, even the easy projects may take up to 100+ hours to complete. I hope by the end of this session you will have a good glimpse on the size of the solution.

For now, let’s take the integration step by step. First, what we need to do is to set up a payment processor to actually tell salesforce that we actually support Cybersource on our site. The name should have the following convention (as you can see let me just pull.. my laser pointer here 👀 ), okay so as you can see the first thing we should have is the vendor name underscore the type, credit card for example. So, the payment processor should have this naming convention: it should have the vendor name that’s CYBERSOURCE underscore(_) the method name which is CREDIT-CARD.

Once we do this we need to create a payment method. The payment method should leverage the payment processor that we have just created. The method, as you can see, is credit card and it should be enabled. It also should use and leverage the processor that we have just created in this dropdown. Down here, we set all of the credit cards and the debit cards that we’re going to support.

Alrighty, so that’s on how to configure the payment processor and the payment method from a high technical aspect. Let’s now move on to the code for a bit.

So once you set up all of these; The payment processors and the payment method, you need to create a new pipeline. This pipeline should be the processor’s pipeline. It should have the same name as the processor and as you can see here it shares the same name with the payment processor that we’ve just created. This is to indicate to salesforce, later on, that this pipeline will be the one that handles all of the operations for this payment processor. This pipeline should handle four main operations:

• Create the payment objects and we’re going to talk about these in detail later on.
• Build the Cybersource request.
• Call the designated Cybersource service.
• Parse the response that we get from Cybersource.

Now, if we go into the authorize (for example) it’s going to call another pipeline and in here (and by the way I chose pipelines just because you can see the sequential steps that we’ve taken better than SFRA maybe), the first things that we’re doing here is creating the objects.. it’s all Cybersource data as you can see. (create ship to and bill to addresses objects, the payment cards, the purchase totals). Later on you’re gonna analyze the request that we send to Cybersource and you’re gonna see this in much detail.

Now, if we go into the authorize (for example) it’s going to call another pipeline and in here (and by the way I chose pipelines just because you can see the sequential steps that we’ve taken better than SFRA maybe), the first things that we’re doing here is creating the objects.. it’s all Cybersource data as you can see. (create ship to and bill to addresses objects, the payment cards, the purchase totals). Later on you’re gonna analyze the request that we send to Cybersource and you’re gonna see this in much detail.

In step two and three this script node builds the request for the authorization call and then it calls the service itself. Okay, so these are three main functionalities out of the four that we’ve talked about.. if you scroll down you’re gonna see the fourth functionality after we actually do the call to the Cybersearch service. Cybersource will return some arguments, that we’re gonna inject as parameters to the pdict (Pipeline Dictionary), and using those we can parse the response to understand and to decide if the card is authorized, if it’s declined, or if it has an error. These are the main four steps that the processor pipeline should do in order to finally handle the payment.

After that we’re gonna create a mapper. The mapper class is one of a kind. It’s a mediator between the real SFCC logic and the payment processor that we have. The mapper’s main functionality is to decide what payment processor should we use. So, it takes the parameters that we’ve passed to the request and it then decides what pipelines should handle this request. So, let’s assume that a user is going to use PayPal, it would not be logical to send him to the Cybersource processor pipeline, right? As you can see the this node, this pipeline call, is a dynamic one.. So once we do all of these checks we know what pipeline we should use. So, this mapper maps the the request to the corresponding pipeline processor. After we build it, we can really just inject it in other SFCC pipelines, like Checkout’s PlaceOrder or the submit payment pipeline, where you can just add the start node and it will integrate gracefully.

Most of Cybersource requests are built upon SOAP, because as we mentioned before it’s a legacy solution, so to properly call the service we need to properly set up the service definition files (WSDLs) and to build all xml requests strictly adhering to the service requirements, I’m not going to go into much detail in here because a colleague of mine did a very good job in detailing how to create a SOAP service in a previous session on the same channel, so if you guys can refer to his session on how to create a SOAP request and how to handle the WSDL files it will help you immensely.

So to recap quickly what we need to do to get Cybersource working:

• Create a payment processor and a payment method from the Business Manager.
• Create a pipeline for the new processor which we called a processor pipeline.
• Create a mapper that detects the type of operation and maps it to the corresponding processor.
• Integrate that mapper into the SFCC logic that we have.

After we got everything working, we need to look at the services that Cybersource provides. Cybersource provides lots of services but each one of those will fall under one of these categories:

• Pre-call Services: these are calls that happen to provide certain critical data to later calls. (Example: payment tokenization).
• Main-call Services: these are the stand-alone services (Example: authorization).
• Post-call Services: these are the services that are related to fraudulent activities and decision manager related services.

What is payment tokenization? we’ve talked about it as a pre-call service but what is payment tokenization?

You know once we want to enter our payment information on any site, you need to have fields for the credit card number, the expiry date and the CVN. As a security measure and for PCI compliance reasons, stores are obligated not to pass, or to save plain or encrypted credit card numbers into their systems or their objects. For example, you can’t save any credit card number not even encrypted into your site. That wouldn’t be PCI compliant because that’s not secure.

Therefore, Cybersource tokenizes the payment before saving it, but what does tokenization mean exactly? A payment token is an encrypted value that combines the card number, the expiry month, year, and merchant id (the merchant id is a unique identifier that specifies the seller for this site).

Maybe now you’re thinking.. okay but isn’t a token still an encrypted value? how can we save it, right? This a very good question and a very valid one.

Payment tokens that we get from Cybersource are encrypted values that we don’t have the private key for. So, there’s an encryption that we don’t really know how to break saved in our system and that’s a bit safer because it is built upon multiple factors like: the number, the expiry date, and the merchant id. Each card, even if it’s the same card on different sites would have a different token id. That’s why it’s more secure.

If you go into the site for now and you enter this, we will make some calls to Cybersource (we’ll go into that into much detail later on), Cybersource will return a token to the site. This token is called credit card token in salesforce, in other ecommerce systems it’s called a subscription id (and i’m mentioning this because later on in the xml you’re gonna see “subscription id” being used). This token can be saved in the database, and can be passed to the subsequent pages with no security concerns. Also, and this is very important, this token can replace the credit card number. So you can pass this token to Cybersource, and i’m going to show you one example of a token later on, but you can pass this token to Cybersource and Cybersource will implicitly know that this is the card number that corresponds to this token.

Let’s look at how we send this request to Cybersource. I have omitted some lines from here because it contains client-sensitive information, I’m keeping the service. In here we’re calling the Flex service. Flex service is one of the methods to get tokens from Cybersource, and we’re going to talk about different of getting these tokens later on. For this service, we’re pulling Cybersource to say.. hey we want a token.. and then the token response we would get is what we call a Flex token. The Flex token contains (and as you can see it’s a JSON object) the token, the masked PAN, the card type, and the signature.

The token part is the token that we’ve talked about and if you notice closely, the last four digits of this token corresponds to the last digits of the credit card number, it’s always going to be this way. The masked PAN is a masked value of the used credit card, and it shows the first six digits and the last four digits of the card, but masks the digits in between. The card type specifies if the card is a Visa card, Mastercard card, or Discover or Amex, or whatever..

We’ve talked about multiple ways of tokenizing these payments. We have Flex, this is flex btw, and we’re going to talk about Flex in higher detail, but let me first elaborate on the other tokenization services that we have. We have the simple order API, which is a legacy software still used out there heavily, there’s also the iframe tokenization and the iframe tokenization is a bit deprecated.. it’s not officially deprecated but not a lot of clients uses it, because it was the first one to be rolled out… and the latest method is the Flex API.

What does the Flex API mean? Once you go into the site, you should as we mentioned you should see this form to indicate where you can add your credit card number and all the information. Now all of these fields will be coming from our side (from the salesforce commerce cloud side), except for this field. This will be injected from Cybersource via an iframe. The iframe will only contain the credit card number and nothing else. So once the user enters any number in this field, we will not be able to have access to it. So, we will only be able to pull the Cybersource token that Cybersource returns to us and that’s a security measure that Cybersource included in the Flex API.

Let’s move past this, and after we return the token we have now all the information that we need we have the expiry dates, we have the card holder name, we have the credit card type.. everything that we want is ready and we have it. So, we need to get into the authorization call, and for that the first stop is creating the payment objects.. and the payment objects are called payment instruments in Salesforce. They are simply DTO (Data Transfer Objects) and by data transfer objects I mean objects that have that have private variables and multiple setters and getters. The whole objective of this payment instrument is to hold credit card information like the credit card number if it’s available, the credit card token, the expiry date, the holder name etc etc..

In SFCC, we have two types of payment instruments;

• Order Payment Instruments.
• Customer Payment Instruments.

The customer payment instruments represents a saved credit card, usually it doesn’t contain the credit card number, neither the masked PAN, it’s just going to contain the token and it’s only associated with a customer object. The sole purpose of this is to represent a saved credit card. The other type is the order payment instruments, and these represent a credit card that is being used in an order. This type of objects can be associated with basket objects and order objects.

How do we create the payment object? i’ve added two ways of creating this using pipelines and using SFRA (and I’ve done this because I want to show you guys how close these implementations are, so if we look at the pipeline steps you’re gonna notice that both of these are very similar). First thing that we need to do, this script node creates an empty payment instrument, so it creates an empty DTO. It’s just creating the payment instrument and setting it out there. Now, the next node would be to call the Flex service and what it does is that it calls Cybersource and requests a FLEX token. Once we have this token, we then have all the information that we need. In the last step, we’re gonna populate all of these values into the payment instrument that we’ve just created. If you like look at SFRA for now, you can see that.. here we’re creating a payment instrument just setting the payment instrument type which is of a method credit card and the total gross price. The second step, is to populate it out of a temporary payment instrument object and this basket payment instrument is connected to the order.. So, it’s actually the same..

Okay, once we have all of these ready, we have only one step missing.. To recap, let’s just look at what we’ve done so far.. we’ve created the payment instrument, we’ve called the service for a token, we have everything that we need, and we have a populated payment instrument at hand. So what we need to do is to authorize the order.. and to authorize the order we need to go and understand the code that we have..

I’ve pulled this out of the IDE because I’ve split out the areas that are confidential to my client. When we try to call an authorize method, it should be done through a helper because, as we mentioned before, Cybersource provides multiple services, so we need to have a helper that each method of that helper would do a certain job. For that, we’ll only look for the authorize credit card method.

Now the first thing that we do here is to check if the card is a saved credit card or a new credit card. If it’s a saved credit card, then we populate the billing fields out of the customer payment instrument that we have and later on we do certain steps, like the authorize payer (this is an optional feature. I’ve worked with clients having this feature enabled and I’ve worked with clients who had it as disabled, so we’re not gonna go into it). Let’s jump to the hook and the 3D request which contains the main lines of the of this authorization call.

Here we’re trying to pull and to create a CCAuthRequest, which literally means an authorization request. We’re going to see the same things that we’ve talked about in the pipelines being applied in here in SFRA code. So as you can see we’re now creating the objects, the bill to, the ship to, and the purchase totals. Then we’re populating those, as you can see, so we’re creating the objects, populating them and then the whole code that we have here is to build the response that adheres to the WSDL files that we have so we can send it to the service and get a valid response, After doing certain steps we really need to find the line that actually calls the service and it should be around here.. So we’re calling the Cybersource transaction service, we’re setting the merchant id, the service request that we have, and the credentials and then we’re calling the service response. (If you actually compare this to the pipeline code, this would be exactly the same). After we do the call, Cybersource will return some parameters that we need to parse and we’re doing that right here. Here’s a success scenario for example and here is an error scenario (The same as the pipeline request).

Once we have the response from Cybersource, it’s going to be three main decisions that we get from Cybersource. Cybersource might accept, reject, or review the transaction. By accepting the transaction, Cybersource actually accepts the amount and authorizes the transaction. If it rejects the card, then the amount will not be authorized out of your card.. it’s just a rejection. If it’s a review, the card will temporarily be accepted and the amount will be authorized but it will indicate later on to the merchant that this operation might need further security measures. The merchant can manually select if he wants to reject or accept the order. However, because the amount was authorized.. if the merchant tries to reject the order, we are going to do a refund to that specific user.

We have analyzed this process from a technical standpoint, but what does authorization actually mean? We’ve seen it in a technical aspect but in business terms what does a transaction really mean? We have lots of transaction types available via Cybersource, but I have picked the main four.. you’re gonna hear a lot of these names if you work on a payment project or ticket. To understand the difference, let’s take this example: you go to Amazon and you buy a certain household item for 100 bucks for example from the seller.. once you place the order, this is called an authorization. Your bank will send you a message saying that that 100 bucks was deposited from your account or something like that. That means that the amount was taken from your account but it didn’t really move to the seller’s account yet. It’s reserved by the bank temporarily. Usually after that the item will ship and the seller actually finalized all the obligations that he has with you and for that he asks the bank to capture the reserved payment because everything went well and he wants to transfer the money. This is called a capture request, and it means that the seller wants to take the money out of the bank’s reservation into his/her account. Now once the bank actually sends the money and deposits it and credits it into the seller’s account then this is called a settlement. Okay, so a settlement means that the seller has now the money in his account.

The final transaction that we have is the reverse authorization, which means an authorization request but in reverse. So it means a refund if the if the seller was not able to ship your item for any reason.. The’ seller will ask the bank to refund you with the amount of the transaction and that happens through a reverse auth. Now one thing to note is that the authorization request is always the first request that we have and any flow of the transactions we do with Cybersource. So authorization will always yield us a transaction id that will be used later on in any subsequent calls with Cybersource. For any further transactions with Cybersource you should indicate the transaction id.

Once you do the authorization you get a transaction id, if you want to do a capture you should tell Cybersource that I need a capture for this this authorization request, okay? The transaction id is the one value that actually maps all of these transactions together.

The anatomy of a Cybersource request and response:

We’ve talked about SOAP services, we’ve talked about the XML that we want to send to Cybersource, and we’ve talked about creating the Cybersource objects and about all of these things but we’ve not seen the request and response in action. So let’s take a look at the request right now. I’ve omitted all of the vital informations like usernames or passwords. Anyways, so here is a request.. this is an authorization request that we usually send to Cybersource. As you can see we’re in the body of the request. First of all, in the header we’re sending the merchant id and the credentials. In the body we’re sending the merchant reference code I mentioned earlier, it usually means the order number and then we have the bill to object (as you can see). This is the ship to object that we’ve seen the code creating. Both of these represent the addresses (so as you can see street one, city, state, postal code, whatever). Please note that we’re sending some information like the ip address and the bill to, we’re going to talk about this later on.

Now we’re also sending the items the customer had bought on this site and as you can see the shipping has a line item because in Cybersource we don’t have a specific item for shipping or we don’t have a specific node designated for shipping. So we send it as a line item instead.

Down there we see the card object. This card object actually contains all of the card information that we entered on the site and as you can see we have the full name, the expiration month, the expiration year, the cv number, and the card type but there’s one thing missing if you can notice.. It is the card number.. So where is it, right? If you look down a bit it’s going to be the subscription id that we have and it’s it’s correctly it’s called a token but we’ve mentioned that other e-commerce platforms call it a subscription id. So here you can find the credit card number.

Okay once we send this xml to Cybersource, we’re going to get something like that.. it’s going to return the reference code for the merchant and the request id (this is the transaction id that we’ve talked about). So any further contact with Cybersource regarding any other subsequent calls should indicate the request id. Cybersource also returns a decision, a reason code, and the request token. This snippet is the most important part of the response of Cybersource. This decision is actually the one that defines if the card was accepted, rejected, or reviewed and that’s it for the response.

The final missing piece of the whole cycle is related to fraud detection and decision manager. There is a scene in the first season of Friends that can demonstrate these concepts accurately. The bank calls Rachel, who is one of the protagonists in the show, because she hasn’t used her card in a very long time, that’s for her is an unusual activity. Let’s watch and discuss later on.

Clip Rolls

As you can see from this video the bank is calling one of one of their clients to see why the why her credit card was not used for a certain amount of time because it’s an unusual activity. This is the same thing that happens for online shopping. Cybersource relies on algorithms and patterns to detect high-risk transactions. For example if your monthly average payments are around let’s say 250 bucks and suddenly you get charged with a 4-thousand bucks receipt, that’s where cyber source intervenes. Cybersource algorithms can also detect if the shopper is the real owner of the card. Things like the billing address, the name of the shopper, the IP of the device (we’ve seen in the request that we’re sending the ip address), the amount, all can help Cybersource detect fraudulent activity.

For example, if your card was issued in the US, and suddenly was used in the Middle East, then the bank will give you a call to determine the validity of this transaction. Once something like this happens or occurs Cybersource will return with a REVIEW decision rather than accept. All reviewed orders go through an extra security step, called the decision manager. The decision manager can provide extra insights in general for the merchant regarding each transaction. The decision manager allows merchants to set rules for fraud detection based on addresses, credit scores, etc.. It even allows merchants to change their rules and see the results instantly via the fairly new Cybersource Decision Manager Replay utility.

In the decision manager, the merchant can either accept or reject the transaction. These decisions happen at the Cybersource control panel. We have a control panel for Cybersource called Cybersource Business Center. So one might want to ask this question: The user was authorized, he got a REVIEW decision on the Salesforce side and an amount of money was deposited from his account. Then the merchant decided to reject the order in the Cybersource Business Center. How can we really sync up both of these systems?

For that each e-commerce site should have a decision manager job that loops on all orders with a REVIEW flag, then the job will make a call to the decision manager’s endpoint to get the final result. If the final decision was a reject, we issue a reverse auth.. (the final transaction type that we’ve talked about) we for that customer. I also believe we had a job session before.. I think Noor Qaneer (one of my colleagues) did that one.. so if you want to go watch her session, that also would be very helpful to you guys (available on the same Youtube channel)..

That pretty much sums up my payment gateway integration session.. If you guys have any questions i’m happy to help..