CyberSource Payment System  —  The implementation guide using Elixir

This is the guide we wanted to find before starting the integration of CyberSource payment system into our project. It will glimpse into the problems faced trying to integrate a new payment system using a SOAP service into an Elixir module.

Beginning

For the project we are developing, our client chose Stripe as the payment processor for the first development stage. Stripe has, without doubt, one of the simplest and well written API documentation I’ve ever encountered. Their examples are pretty good and within no time integrated it into our project in Elixir using the stripity_stripe plugin.

As we expected a large volume of payments in the future, our client negotiated better fees with another payment processor, CyberSource.

CyberSource is an eCommerce payment management company and was bought by VISA in 2010. They share the same technology as the VISA API, that is a very well documented API, but unfortunately their own REST API was still in beta. We needed to use Apple Pay and Android Pay, but we couldn’t use their REST API, because this type of mobile payment (Android Pay and Apple Pay) is only available through the SOAP API.

It took us quite some time to understand that and, for a long period of time, we were searching their library documents, desperately looking for examples to test and to understand how to configure any SDK (PHP or JAVA) to work with mobile payments.

To increase the difficulty of this research, we had to handle an intermediary, Global Payments. They are resellers of CyberSource and when we were trying to setup and create the implementation for our project in Elixir some things didn’t add up. The options seen in the CyberSource documentation didn’t match the options we had in our CyberSource Business Center.

We contacted CyberSource support to understand what we can and can’t do and after that call the solution was obvious, we needed to use the Simple Order API (a SOAP service), because it was the only production service available that handles Apple Pay and Android Pay.

After this, we discovered that the Apple Pay and Android Pay integration needed in CyberSource, to have less exposure to PCI DSS requirements, must be done by our account manager in Global Payment. The steps were the following:

• Get CSR file with Merchant Id information from CyberSource to send to Apple, in order to create the Apple Pay certificate;

• Get a Public Key to encrypt data card information in Android app to be decrypted in CyberSource servers;

After some exchange of emails we had both payment types configured and ready to be tested.

Having a middle man between the developer team and the payment company made things hard to implement, because some miscommunication was always present and we needed some time to understand if we were missing something or if the problem was on CyberSource side.

First successfull payment

The documentation provided by CyberSource has almost all the information needed although the way their information is structured is very confusing. Some documents took some trial and error testing with Postman (check this article to know how to handle WDSL in Postman) in order to make successful requests to their API and better understand what kind of data we needed to send in our backend.

After some attempts, we successfully made several requests to authorize, capture and refund a payment! There were still some issues like the AVS check (address check) to know if it matches with the credit card information of the user. This is something that we didn’t have to handle in Stripe and can be turned off for some credit cards that don’t mark it as mandatory (for US/CA cards is mandatory).

Another strange thing that we needed to handle (and that we didn’t have in Stripe) is selecting the card type, like Visa, Mastercard, American Express, etc. This is a little bit annoying, because we had to add more code to do a simple thing that could be done on CyberSource side. In our case, we ask Android and iOS devices to send the card type with the payment token.

Implementation in Elixir

In terms of technologies, CyberSource provides a few SDK’s for different languages, like C++, C#, Java, PHP and Objective-C. Developers that use Node, Python, Ruby, Elixir or another language, need to implement a solution with the SOAP API, and we all know that SOAP should have died a long time ago.

There are some packages to handle SOAP in Elixir, but all of them are using the soap libraries for Erlang, and that was another issue.

After some days doing some research on how to implement the right way of using the SOAP API with our project, we ended up deciding to use HTTPoison to send requests.

The way we were doing the test requests in Postman could be applied to do the same type of requests in HTTPoison. I know that this isn’t the best integration of SOAP services, but diving into Erlang wasn’t a viable option at that time for us and we will migrate this to a REST version as soon as it is available, but for now we have a working package.

As explained in the Postman link, we had to put the WSDL link into the URL field, select the request method to POST and put the following XML structure on the body parameter, selecting the language (content-type) as XML:

<soapenv:Envelope xmlns:soapenv=”http://schemas.xmlsoap.org/soap/envelope/" xmlns:pm=”http://www.getpostman.com/"> <soapenv:Header> <Security xmlns=”http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd"> <UsernameToken> <Username>user</Username> <Password>pass</Password> </UsernameToken> </Security> </soapenv:Header> <soapenv:Body> … </soapenv:Body> </soapenv:Envelope>

This is a standard SOAP request with the security header present. The first part is the authentication header that we need to send with our credentials to authenticate in the Simple Order API (SOAP).

These credentials are available in CyberSource Business Center page under Account Management > Transaction Security Keys > Security Keys for the SOAP Toolkit API. The username is the merchant id and the password is the base64 string generated in the page above.

After testing different types of requests we ended up with a working solution in Elixir to use CyberSource SOAP API, that you can take a look into our GitHub repository. For now it only support payments with Apple Pay and Android Pay, but I expect to implement credit card transactions in the future and migrate to a REST API as well, as soon Android Pay and Apple Pay are available on it.

This was our first elixir package we’ve created and it is really great to contribute into Elixir rising community with it.

Final thought

I hope this post can help you using the CyberSource API with mobile payments or implementing SOAP APIs in your Elixir project.

Sometimes the information we need isn’t available in places we expect it to be, so it’s probably better to try to contact support to find the right solutions for our problems.