ClientPay® is a web-based payment processing solution that allows Aderant users to accept credit card payments based on up-to-the-minute information from your system. ClientPay also posts payment information back to your system, thereby eliminating the need to enter the information manually. As such, ClientPay requires a secure means to communicate with your Aderant database through the ClientPay web service. This guide shows you how to enable this service.
What you will need:
- ClientPay web service
- SQL script to be run against the Aderant database
- A server with IIS installed (version 7.0 or higher) with TLS 1.2 or higher enabled
- A .pfx file to create a secure endpoint in IIS
- A static IP address and a port that we can use to contact the web service
- Aderant's Generic Importer tool
IIS comes free with all Windows Server versions. The web service and script can be downloaded from a link you should have received when your organization signed up to use ClientPay. If you have not received this link, please contact support@clientpay.com. The payment card industry (PCI) requires TLS 1.2 or higher for compliance. If your server does not allow for secure messages via TLS 1.2 or your users have older browsers that do not support TLS 1.2, you will experience disruptions when accessing ClientPay.
We can issue you a free .pfx file, or you can have one created by a certificate authority. Click here for instructions on how to install the certificate. Our .pfx files are self-signed. Although it is not traditionally best practice to use a self-signed certificate for Production purposes, this is a different use case from other web sites as our web servers should be the only entity that contacts your web service. We have the root certificate for our .pfx files so all communication between your web service and our web servers will be encrypted via https.
For additional security, ClientPay can also be used with client certificates. This can be setup once we verify our site can connect to your web service. In short, if you use client certificate security, the web service will require that whatever entity is contacting it has a certain certificate and if it is not presented, no connection will be made. For a more in-depth explanation of client certificates, please read the short article at https://support.microsoft.com/en-us/help/907274/iis-and-client-certificates. We issue the certificates used for this purpose.
While the ClientPay SQL script does not manipulate any existing tables, procedures, or data, as an extra precaution we recommend that you back-up the database prior and run it at a time when no one is using the system.
Aderant's generic importer tool is required in order to post receipts from ClientPay to Aderant. If you do not have it, you will need to contact Aderant to obtain a license for it.
PREREQUISITES
Static Domain or IP Address, Firewall Port, ClientPay SSL Certificate Installation
For our site to contact your web service, we will need to have a static IP address. You cannot see your external IP address from your machine but it can be obtained by going to a website such as https://whatismyipaddress.com. We will also need a port number. ClientPay accepts ports 443,444, 8080, and 32321 – please select one of the values. You may need to configure your firewall and/or NAT rules in order for our website to make a successful connection.
A firewall configuration may be needed when assigning this port. We offer free SSL certificates for use with ClientPay.
Microsoft .NET 4.0 Framework
At a minimum, the 4.0 version of the Microsoft .NET Framework must be installed on the server before continuing the installation. The .NET Framework is free and can be downloaded from Microsoft.
To determine what versions of the .NET Framework are currently installed on your server, navigate to the “Windows\Microsoft.NET\Framework” folder using Windows Explorer. If the 4.0 version is installed you will see a folder with a prefix of “v4.0”.
SQL Server Management Studio
Our instructions assume you have SQL Server Management Studio installed. It is not strictly a prerequisite, but it makes it much easier to use SQL Server if you are not very familiar with using the command line. It is more than likely already installed if you have SQL Server, but if not, you should be able to download it for free from Microsoft.
Internet Information Services (IIS)
The ClientPay web service is hosted in IIS. To determine if IIS is installed on your server, look in the “Administrative Tools” folder. If it is not currently installed, you may need to go to Server Roles and install it (it comes free with all Windows Server operating systems). Please note that in Windows Server 2012, it is possible that a search for ‘IIS’ on the Start screen will not find it. So, if you are unable to find it that way, please also look in Administrative Tools.
Installing IIS (version 7.0 or higher):
To install IIS on Windows Server 2012, you need only add the appropriate roles in the Server Manager, which is probably on the task bar but can also be found by searching for it on the Start screen.
Version 2012 ONLY - Please ensure that the following server roles are installed:
To install roles, open the Server Manager, select Add roles and Features, and click next (several times) until you get to a page entitled ‘Select Server Roles.’
Page 1 (of Select Server Roles)
- Application Server
- Web Server (IIS)
Page 2
- .NET 4.5
- ASP.NET 4.5
- HTTP Activation (inside WCF Services)
- IIS Hostable Web Core
Version 2008 ONLY
Once the installation is complete, you may need to register ASP.NET with IIS. This is normally the case if you receive a 405 Error when testing the web service. We suggest attempting the below remedy only if you see this error after configuring the web service.
This can be accomplished by opening a command window as an administrator, navigating to the folder that contains the aspnet_regiis.exe assembly, and typing aspnet_regiis -i. The assembly will normally be located here: C:\Windows\Microsoft.NET\Framework64\v4.0.30319. If you are using a 32-bit version of Windows, this will probably be the location instead: C:\Windows\Microsoft.NET\Framework\v4.0.30319.
IIS CONFIGURATION
Launch the “Internet Information Services (IIS) Manager” application from the start menu. Navigate to the correct server click on “Application Pools”. Then select “Add Application Pool”. Refer to Figure 11 below.
Figure 1
You can name the application pool anything you want, but we suggest something with ‘ClientPay’ so it will be easy to remember its function. Here we will refer to it as “ClientPay App Pool”. Select the 4.0 version of the .NET Framework and “Integrated” for the managed pipeline mode. Make sure that the “Start application pool immediately” is checked. Click the “OK” button to continue. Refer to Figure 2 below.
Figure 2
You will have to configure the newly created application pool to allow access to system resources like the Aderant database. Select the “ClientPay App Pool” entry and then click the “Advanced Settings” link. Refer to Figure 3 below.
Figure 3
Note: the below steps for configuring the application pool identity are only necessary if you intend to use integrated security for accessing SQL Server. Using integrated security means you will use the identity on the application pool as the credentials for logging into SQL Server. If you choose to use integrated security you must have a corresponding login in SQL Server that has permission to access the ClientPay stored procedures in the Aderant database. So if you have an Active Directory user called domainName\userName that you use for the Application Pool Identity, you must have a corresponding SQL Server login called domainName\userName with permission to run the ClientPay stored procedures in the database. The domainName\userName SQL Server login must also be configured to use Windows Authentication as opposed to SQL Authentication.
If you choose not to use integration security, or if you can’t because you are installing the web service on a machine in a different domain from your Aderant setup, you will still need to use a SQL Server login to access the ClientPay stored procedures, albeit with SQL Authentication. You will also need to enter the login name and the corresponding password into the connection string. Please see the section entitled ‘Verifying the Web Service’s Connection Strings’ for more information on this subject as well as examples of what your connection string might look like. Click “Identity” and then the “…” button to the right to modify the Identity settings. Refer to Figure 4 below.
Figure 4
If you are using integrated security as discussed above, you will need to enter a Custom Account in the box that pops up (Refer to Figure 5). If you are not using integrated security you do not need to change the identity from ApplicationPoolIdentity.
Figure 5
Now, click “Sites” under the server name and then “Add Web Site…” to host the web service. Refer to Figure 6 below.
Figure 6
You can name the site anything you want, but we suggest something with ‘ClientPay’ so it will be easy to remember what it is doing. We will refer to it as “ClientPay Web Service” here. Click the “Select” button and assign the “ClientPay App Pool” for the application pool. Assign the port and leave the “Host name” empty and IP address at “All Unassigned” unless you have a reason to assign a specific address. The port must be either 443,444, 8080, or 32321. You will want to configure your firewall and/or NAT rules to allow communications via the port you choose. If you have not yet installed a .pfx file (instructions for this are included below) just select ‘http’ for the binding type. You will be able to change this later. Otherwise select ‘https’ and the .pfx file you intend to use. Refer to Figure 7 below.
Figure 7
Click the “…” button and navigate to the “Inetpub” folder. Refer to Figure 8 below.
Figure 8
Unless you have already created a folder for this purpose, click the “Make New Folder” button. Refer to figure 9.
Figure 9
You can name this folder anything you want but we will refer to it as “ClientPay Web Service” here. Again, we recommend something with “ClientPay” in the name. Additionally, there is no technical requirement to put the service inside the inetpub folder. However, we recommend it as this is typically where anything served by IIS is placed and it is the first place anyone will look if they are not familiar with ClientPay.
You will have downloaded a web service .zip folder from the link you got when your organization signed up for ClientPay. Once the folder inside inetpub is created, unzip it and place the bin folder, global.asax file and web.config file that are inside in the folder. These three files make up the web service.
Binding the IIS Endpoint with a .pfx file
A .pfx file is needed to create a secure endpoint. Without one it is not possible to create an https endpoint.
In order for a .pfx file to be included on the list of those you can choose from for bindings, you must first install it in the personal store of the machine account on the machine you are installing the web service on. Please click here for instructions on how to do this if you are not sure.
Once this step is complete you should be able to use your .pfx file to bind your endpoint in IIS. You can bind the endpoint with a .pfx file either while you are creating the site initially or afterward by clicking on bindings (far right of the IIS console while you have the ClientPay site you created on the left-hand side selected – refer to Figure 10) and then adding a new https binding. You will not be able to change an http binding to https and you will not be able to delete the binding if there is only one, so if you do it this way you will need to create a new binding and then delete the original one afterward. Assign the port and leave the “Host name” empty and IP address at “All Unassigned” unless you have a reason to assign a specific address. The port must be either 443,444, 8080, or 32321.
Figure 10
If you are using a Persolvent-generated .pfx, you will see a warning regarding an intermediate certificate. You can click OK and ignore this.
Figure 11
Patching the Aderant Database
Patching your Aderant database does not change any of your existing data. It simply creates tables and stored procedures that allow the ClientPay® web application to communicate with your Aderant application. The script assumes the physical name of the database is “ADR_LIVE”. If this is not correct, you will have to modify the script before running. The name of the database only appears on the very first line of the script so that is all you would need to modify.
Start the SQL Server Management Studio and login into the server.
Note: Persovent recommends that you take a back-up of your Aderant database before continuing.
Open the .sql script included in your installation package and then click the “Execute” button. This will create new tables in your Aderant database. If the script runs successfully, it will confirm that one row was modified – this is a version number that we insert into a table we create to hold it.
Verifying the Web Service’s Connection Strings
Navigate to the Aderant Web Service folder located in inetpub. Within the web service folder, open the web.config file in notepad.
Within the web.config file, verify that the connectionStrings tag accurately reflect the topology and desired user access of your environment. See Figure 12 below for the exact location of the connectionStrings tag. If this is not correct, update the Strings to reflect your environment and save.
Figure 12
The connection string will look something like this:
<connectionStrings>
<add name="Aderant" connectionString="server=(local);Initial Catalog=ADR_LIVE;Trusted_Connection=Yes;Integrated Security=SSPI" providerName="System.Data.SqlClient" />
</connectionStrings>
We do not recommend installing the web service on the same machine as SQL Server as SQL Server tends to take up all available RAM at times. However, if you only have one server then you have no choice, and there are a number of organizations that do this so it is not untenable. If this is the case, the “server” value in the connection string should be ‘(local)’. If this is not the case you will need to remove the parentheses and enter the name or IP address of the server that your SQL Server instance is on. If this server is in the same domain as the web server, you can use the server’s name or an internal IP address. If it is not in the domain you will need to use the external IP address. You can use the ipconfig command in a command prompt to get the internal address and websites like https://whatismyipaddress.com or www.ipchicken.com can tell you your external address.
Note: if you have a named instance of SQL Server, the “server” value will look like this:
server=machineNameOrIPAddress\instanceName;
Named instance are rare so if you are not sure if you have one, you probably don’t. But you can find out by opening SQL Server Configuration Manager (this should be installed on the machine where you have your SQL Server instance), selecting SQL Server, and viewing the information that comes up as a result. Next to where it says ‘SQL Server’ there will be a name in parentheses; if that name is MSSQLSERVER you do not have a named instance, and if it is something else, that is the name.
Integrated Security
There are two ways for the web service to connect to SQL Server: integrated security, where the Active Directory account listed as the application pool’s identity makes the connection, or through the connection string where SQL Server credentials are simply entered into the connection string. The second option requires you to enter a username and a password into the connection string.
server=myServerAddress;database=ADR_LIVE;user id=myUsername;
password=myPassword;
If you use integrated security, you must have a corresponding login in SQL Server that is able to access the Aderant database. The name should match exactly, which often means the format domainName\userName.
appSetting Descriptions
ReceiptEntryDirectory – Create a folder somewhere that the Aderant web service can access. You can call it anything you want but we recommend something like ‘ClientPay_Uploads’ as it will hold text files which are written as part of the receipt posting process. Update this appSettings with the physical location and name of this folder. Important: You will have to create this folder.
MatterCurrency – If you use a currency code other than USD for US Dollars, update this accordingly otherwise leave as is.
Debug – In general you should leave this off. When on, the web service will write informational entries into the server’s event log. This is useful if someone at Persolvent is trying to track down possible issues with the web service, but will otherwise just create clutter that probably won’t be meaningful to your organization.
Testing the web service
If you have completed all the above steps, it is time to run some tests to see if the web service is running properly. To see if the web service is working, open a browser on the machine where it is installed. Type the following url into the browser where ‘portNo’ is the port number specified on the IIS binding. If you are using port 443 you can skip the colon and the port number entirely as 443 is assumed when no port is specified.
https://localhost:portNo/clientpay/getdata
You will probably need to click through a certificate error. This is expected, so click through it. As this is the first time the service is being contacted, the call may take a little while (10-20 seconds, possibly). If everything is working, you should see a short string of json data in the browser. Alternatively, you might be prompted to download this data. If you are, do download it and then you should be able to see the json data in notepad. Either of these outcomes means the web service is installed properly. If you do not get the data, it means something is still not right. If this is the case, you will hopefully see an error message that gives you a clue as to what still needs to be done.
Test the database connection
If you got the json data from the first test, it is time to test the database connection. Use this url:
https://localhost:portNo/clientpay/getversion
This call retrieves the ClientPay version number we inserted into the ClientPay_Version table that was created when you ran the ClientPay SQL script. If you get a short json string that includes a version number, you have successfully connected to your database. If you do not, you should get an error message that tells you what went wrong. Fortunately, SQL connection errors are normally pretty straightforward. The more generic sounding errors usually indicate that the web service is not finding your SQL Server instance. If that is the case, there is probably something off in the connection string – perhaps the server has the wrong name or IP address, or maybe you do have a named instance after all.