MIL was the first organization to integrate Salesforce Government Cloud with Pay.gov on behalf of a federal agency. Pay.gov is a service available to U.S. government agencies that conduct payment collection and processing activities. Pay.gov can collect credit card or bank account information from the user, or use other authorized payment sources such as PayPal. It can also manage payment processing so that government agencies don’t need to access sensitive account details, making them less vulnerable to cyber-attacks.
As of today, MIL’s Salesforce to Pay.gov integrations have processed over $2M in payments and refunds for the U.S. Department of Commerce.
When integrating a Salesforce implementation with a Pay.gov SOAP-based web service, three main challenges often occur: enabling communication; generating code; and using the client certificate. While challenges encountered during our Pay.gov integration are discussed below, they may also apply to other SOAP service integrations with Salesforce.
Challenge 1: Enabling Communication with Pay.gov
Calls to a Pay.gov web service were restricted by IP address and those that were not on their whitelist (those that have been accepted, approved, or recognized) were rejected. Since an instance of Salesforce runs on hundreds of different servers, we could not predict which calls, if any, would be restricted. To overcome this challenge, MIL worked with Salesforce support to identify our virtual outbound IP addresses. In our integration from Salesforce Government Cloud, we used two IP addresses, specified here as outbound API addresses. These virtual IP addresses don’t change no matter how many servers Salesforce has in the cloud. Pay.gov whitelisted the virtual IP addresses and this problem was solved.
Challenge 2: Generating the Code to Communicate with Pay.gov
The WSDL file from Pay.gov shows which operations are available and how data should be structured. However, in most cases it won’t simply be one file. Pay.gov uses XML Schema Definition (XSD) files to define the schema of the WSDL file. In other words, the XSD files state what is valid to put in the WSDL file. Salesforce has an option to create class files from a WSDL file. However, it doesn’t permit WSDL files that reference XSD files.
The first step toward resolving this was to manually edit the WSDL file to copy and paste everything from the XSD files into it. In some cases, further editing of the WSDL file was necessary for any references that Salesforce won’t permit. We knew what was permitted by attempting to create classes from the WSDL file.
In order to create classes, go to the “Apex Classes” page in Salesforce and click on “Generate from WSDL.”
Once the WSDL was edited to meet Salesforce’s requirements, this option created the asynchronous and synchronous class files. To communicate with Pay.gov, we made a call to the synchronous class file from our Apex code.
During this process, the asynchronous file that was generated was not needed. Additionally, it is generally useful to comment on all parts of the class file that are not used. Because of the need to create a test class, commenting the classes and methods that are not needed will simplify this test class.
Challenge 3: Using the Pay.gov Client Certificate
Pay.gov will provide you with two certificates; one for testing against their QA site and one for production. These certificates need to be modified so they can be imported into Salesforce. Modifications include changing the alias name of each certificate, importing the certificates into a Java Keystore, and making sure the password for each certificate is between six and eight characters. With these modifications, you will be able to import the keystore through the Certificate and Key Management page. A future article will discuss specific instructions on putting the certificates in Salesforce.
Lessons Learned
MIL’s integration between Salesforce and Pay.gov was by no means straight-forward. But by making use of a virtual IP address, creating code from a WSDL file, and modifying the client certificate, our team made this first-of-its-kind integration happen. Hopefully, these tips based on our experience will help you in your future integration projects.
About the Author
Cary Freeman is a force.com developer with 17 years of Java development and two years of Salesforce development. He holds 12 certifications, including a Salesforce Certified Application Architect, Salesforce Certified System Architect, and Project Management Professional (PMP).