You can also use the PDF manual found here.

Prerequisites

Before you start intregrating a system with PayEx Connect please make sure that:

• You have basic knowledge of Web Services, including WSDL, Soap and WS-Security.
• You understand that PayEx Connect is designed to simplify integration for clients using Microsoft .Net, Java Axis or other frameworks that have built-in support for WS-Security and other W3C standars.

Detailed documentation is available on a per service level. Detailed documentation for the Sample service is always supplied by default.

Security

This section describes the security concepts  that PayEx Connect use.

Service authentication

Username and password is used for authentication. Your company number provided by PayEx is used as username. The password is client unique and provided by PayEx. Replay attacks is prevented by using message timestamps and nonces.

The security token consists of the following elements:

A failed authentication will generate error code 3011 (see Custom error codes below). Possible causes for a failed authentication may be invalid client IP, invalid company number or invalid password.

Role based security header

The role based security header is used to restrict the usage of services to predefined levels and enable trace logging. It contains EndUserName and EndUserRole. EndUserRole is used if the referrer IP is associated with a ServiceConsumer. EndUserName is only used for logging purpose. Contact PayEx to learn more of the proper solution for your company.

The RoleBasedSecurityHeader consists of the following elements:

Service Authorization

PayEx Connect restrict the company numbers allowed for each client. Different company numbers may have a different subsets of services available through PayEx Connect. Requests to an unauthorized service will generate error code 3011 (see Custom error codes below).

The functionality provided by some services may differ based on company level rules. This may result in unused input variables or empty data responses.

SOAP Request

This is a sample SOAP request.

Error handling

All errors is formatted according to the current standard for SOAP Faults. Detailed information such as error code, description and id can be found in the detail element.

Custom error codes

Input and Output formats

Date, time and amounts are all formatted to a commonformat before returned to the client.

Session and versioning support

Some Crm web methods utilizes optimistic versioning concurrency control to ensure object consistency. This requires per-user session management by the service consumer. Sessions state is supported through standard Http cookies.

The session sliding timeout limit is 30 minutes.

Multiple users on the consumer system can’t share the same session against PayEx Connect. If the service consumer handles multiple simultaneous users, one Http session cookie must be managed for each end user.

The SampleService web service contains sample web methods supporting per-user sessions. The Sample service can be used for testing and developing per-user sessions support in the consuming application. See the sample service manual for details about sample methods.

Usage Samples

Microsoft DotNet 2.0 and WSE 3.0

Enabling WSE support

Before adding any Web references you need to enable WSE. This is done by right-clicking the project in the Solution explorer and selecting “WSE Settings 3.0..”. This brings up the “WSE settings 2.0 tool” that helps you to configure all the settings for WSE.

Enable WSE by selecting “Enable this project for Web Services Enhancements”. This option adds the required settings to the applications configuration file and ensures that all Web references added later will support WSE.

Fig. Enabling WSE Support

Defining security policy

Next define the Policy to be used in all web method requests. Click the Policy tab and select “Enable Policy”. Press the “Add” button and provide a name for the policy, i.e. “PayExConnectPolicy”, and click OK. This brings up the “WSE Security Settings Wizard”.

Select “Secure a client application”. Select “Username” to support the UsernameToken model used by PayEx Connect, as shown in the image below.

Fig. Autentication settings

Specify if the username and password should be managed from code our through the policy file. In this example we manage these properties through code, as shown in the image below. Click Next.

Fig. Specify Username Token in code

Validate that WS-Security Extensions are enabled and select the “None (rely on transport protection” option, as shown in the image below. Transport protection is managed through the SSL protocol. Thus there is no need for additional signing and encryption of SOAP messages between the client and PayEx Connect.

Fig. Message Protection

After the wizard has completed, the policy will be listed in the “WSE settings 2.0 tool” as shown in the image below. The wizard also adds the file wse3policyCache.config  to your project in Visual Studio.

Fig. Application policy

Adding Web Reference

The Web Reference must be added after WSE support is enabled. Any Web References added before enabling WSE, will be missing the proxy classes that supports WSE.

Start the “Add Web Reference” wizard by right-clicking the project in Solution explorer and selecting “Add Web Reference..” from the popup menu.

Enter the URL to the sample Web service in PayEx Connect,
https://connect.payex.com/SampleService.asmx. Specify a name that identifies the service, i.e. “SampleService”, and click Add Reference.

Fig. Adding web reference

Calling service

The final part of this sample is the code that prepares the request and invokes the web method. This code consists of four different parts: setting credentials, preparing and submitting the request, processing the response and error handling.

Fig. Sample code

Setting credentials

Create a new UsernameTokenProvider and set the username and password properties (The username represents the company number supplied by PayEx). Add the newly created token as the client credentials through the SetClientCredentials method. Refer to the policy name, specified when defining the security policy, through the SetPolicy method.

Preparing and submitting the request

Create a new instance of the SampleMethodRequestType class and set the properties. Execute the web method and store the response in a SampleMethodResponseType object.

Processing the response

The response object encapsulates all the information supplied by the service request. The information can be accessed through properties and sub-objects of the response object.

Error handling

Separate SoapExceptions from other error types when catching errors. A SoapException triggered by PayEx Connect contains additional information in the detail-element such as error code, description and unique id.

Microsoft .NET WCF and WSE

Adding service reference

Right-click on the project and select "Add Service Reference..."

Fig. Adding service reference

Open app.config/web.config and change Security mode to TransportWithMessageCredential.

Example application

Java 5 JWSDP 2.0

This sample uses Java Web Services Developer Pack 2.0 from Sun Microsystems.

Installing JWSDP

Java Web Services Developer Pack enables web services for the Java5 platform. Installation packages can be obtained here:

https://www.oracle.com/technetwork/java/webservicespack-jsp-140788.html

Download and install using default install options.

Project setup

Create a new project in your favorite IDE and add the following files to your classpath:

<JWSDP-HOME>/jaxb/lib/*.jar

<JWSDP-HOME>/jaxp/lib/*.jar

<JWSDP-HOME>/jwsdp-shared/lib/*.jar

<JWSDP-HOME>/sjsxp/lib/*.jar

<JWSDP-HOME>/saaj/lib/*.jar

<JWSDP-HOME>/xws-security/lib/*.jar

Security configuration

Create a new file named client-wss-config.xml and add the following content:

A sample SecurityEnvironmentHandler can be found here:

<JWSDP-HOME>/xws-security/samples/jaxws2.0/simple/src/simple/client

Generate client proxies

JWSDP ships a utility called wsimport that generates client proxies from a wsdl-url. Use the following command to generate proxies:

wsimport.bat –keep https://connect.payex.com/SampleService.asmx?wsdl

Proxies will be generated in the current directory. Make sure the generated proxies are added to project classpath.

Sample application

The following code snippet resembles a sample application calling sampleMethod:

Notice that the sample code expects to find the security configuration file in /foo/bar/. Adjust to your own environment.

PHP

NuSOAP library can be found at http://sourceforge.net/projects/nusoap/

The following code will call the SampleMethod in the SampleService with the argument “Hello Connect!”.