Commerce Web Services Overview

This section provides an overview of the components and concepts related to the development of client applications that communicate with Commerce Web Services (CWS) through the implementation of the SOAP/REST APIs.

What is Commerce Web Services?

Commerce Web Services (CWS) provides payments integration access to software companies, financial institutions, and service providers seeking easy access to new payment services through the integration of a single API. For developers using .NET (C#/VB), Java, PHP, Ruby on Rails, and other object oriented development languages, documentation and support for payments integration is provided for both SOAP and REST implementation methodologies.

Integrating payment services within the applications using CWS provides an easy, low-cost, and efficient development experience. Utilizing a language neutral integration path, developers familiar with object-oriented languages are able to quickly enable access to multiple payment services and providers, while providing support for complex workflows. Seamlessly integrate host or terminal capture transaction processing workflows and value-added services supporting multiple payment types, including Bankcard Processing (BCP Credit/Debit), Stored Value Account (SVA), and Automated Clearing House (ACH).

CWS provides the following benefits to application developers:

  • The comprehensive, yet simple API supports complex workflows and features such as line item data.
  • Provides intelligent data management allowing you to store only the data needed by the application.
  • Implements strong/mutual authentication of transaction originators.
  • Supports multiple Bankcard payment types, such as Credit Cards and Debit Cards using the same API. Simply add the services your customers demand.
  • Reduces maintenance costs by enabling a single integration to multiple service providers; thereby eliminating the need to maintain several one-to-one integrations.
  • Open new sales channels by publishing your solution to a Commerce Marketplace giving reach to thousands of sales representatives—from payment processors, acquiring banks, and ISO’s—searching for the right solution for their customers.

What is SOAP?

The SOAP (Simple Object Access Protocol) protocol specification is used to exchange structured information in the implementation of Web Services in computer networks. It relies on XML (Extensible Markup Language) as its message format, and usually relies on other Application Layer protocols (most notably Remote Procedure Call (RPC) and HTTP) for message negotiation and transmission. SOAP can form the foundation layer of a web services protocol stack, providing a basic messaging framework upon which web services can be built.

A SOAP message could be sent to a web service-enabled web site with the parameters needed for a search. The site would then return an XML-formatted document with the resulting data. Because the data is returned in a standardized, machine-readable format, it could then be integrated directly into a third-party site.

What is REST?

The REST (REpresentational State Transfer) architecture was developed in parallel with the HTTP/1.1 protocol based on the existing HTTP/1.0 design. The REST-style architecture consists of clients that initiate requests, and servers that process these requests and return appropriate responses.

Requests and responses are built around the transfer of "representations" of resources. A resource is any source of specific information. In order to manipulate this information, clients communicate with a server via HTTP and exchange representations of these resources (the actual document conveying the information). A representation of a resource is typically a document that captures the current or intended state of a resource.

When browsing the World Wide Web, you enter a Uniform Resource Locator (URL) in your web browser in order to see a specific web page. The web page is considered a resource and is usually a document in HTML format. It could also represent a record in a database, or even the database itself, that is displayed on an HTML page. This concept was written into the HTTP specification. The REST principles build on top of the HTTP specification and its URL/resource relationships.

URLs are hierarchical in nature. URLs that identify a collection of child resources then adding a new segment will identify a resource within the collection. As a result, collections of collections can result in long URLs.

Consider the following example:

URL Description
https://[base_URL].com/JoyOfCooking Returns the entire resource called Joy Of Cooking.
https://[base_URL]/JoyOfCooking/Chapter1 Returns the first chapter of the Joy Of Cooking resource.
https://[base_URL]/JoyOfCooking?topic=baking To filter on a resource, query parameters can be added to the URL. This URL returns all topics on baking in the resource.

REST Uniform Resource Locator (URL) Hierarchy

HTTP Actions

Once you know the location (URL) of a particular resource (or collection of resources) you can perform various HTTP actions on them. The following HTTP actions are available:

  • GET – Retrieves a resource. Entering a URL in your browser’s address bar initiates the GET action.
  • POST – Creates a resource. This is used to add a new resource to a parent resource.
  • PUT – Updates an existing resource or creates a new resource at the URL specified if it does not exist.
  • DELETE – Removes a resource.

Since POST and PUT actions are used to add or alter data on the web server, they include a message body that contains the specific data to add/update. For example, an HTTP-POST requires a URL, the POST action, and the message body.

 


 

Component Architecture

Commerce Web Services delivers the fastest, lowest cost, and simplest way to integrate multiple electronic payment options. With Commerce Web Services, payment processing becomes a lightweight component of virtually any software application. Commerce Web Services supports SOAP (1.1/1.2) and REST implementations; providing a language-neutral integration methodology for the consumption of payment services.

The high-level CWS component architecture is illustrated below.

Figure 1: Component Architecture - Commerce Web Services

The Commerce Web Services architecture is divided into two distinct services:

  • Service Information Service – Encompasses all functionality related to the authentication of transaction originators, discovery of available transaction services, and the management of application configuration and Merchant Profile data.
  • Transaction Processing Service – Encompasses all transaction processing functionality.

 


 

Web Service Endpoints

Each web service is accessed through Web Service Endpoints. There are two corresponding types of Commerce Web Service endpoints—Service Information and Transaction Processing.

Each Commerce Web Service web service endpoint and their supported functions are illustrated below:

Figure 2: Commerce Web Service Endpoints

Service Information Endpoints

Service Information (SvcInfo) endpoints provide the following functionality:

  • Authentication of the identity token (associated with a Service Key) during the sign-on process using originator credentials in exchange for a session token.
  • Retrieval of service information for available services, including supported transaction processing operations and features.
  • Retrieval of application configuration data, which defines the characteristics and configuration information associated with the application.
  • Retrieval and update of merchant profile onfiguration data needed for transaction processing.

For detailed information about Service Information operations, refer to Preparing the Application to Transact.

Transaction Processing Endpoints

Transaction Processing (Txn) endpoints provide the following functionality:

  • Transaction processing, including Bankcard, Automated Clearing House, and Stored Value Account
  • End-of-day transaction settlement processing
  • Account verification and inquiry

Note: The functionality supported by Transaction Processing endpoints depends on the payment services authorized for each merchant Service Key.

For detailed information about Transaction Processing operations, refer to Transaction Processing.

Service Keys

A Service Key is a globally unique identifier assigned to all certified applications (aka "transaction originators") for authentication and subsequent consumption of services running on the Managed Commerce Services Platform. An identity token is then generated and associated with the application’s Service Key. A single application can operate on behalf of one or more Service Keys.

 


 

Accessing Endpoints

Applications communicate with each Web Service Endpoint using endpoint URLs. There is a primary endpoint URL and a secondary endpoint URL. Your application does not need to make any special accommodations when interacting with these primary and/or secondary endpoints. They merely provide failover functionality in the event that one endpoint is not available.

Should the primary endpoint result in an unsuccessful connection, your application should try the secondary endpoint. In the event that neither endpoint URL results in a successful connection, the application should alert the user that no endpoints are available and they should contact their administrator.

Applications should first default to the primary (cws-01) endpoint URLs. If connecting to the primary endpoint URL is unsuccessful, the application should attempt the secondary (cws-02) endpoint URLs. Administrative users must be allowed to view and modify these URLs as needed.

CWS Endpoint URLs
Service Information Endpoints
SOAP
Primary https://api.nabcommerce.com/2.0.18/SvcInfo

Certification Environment:
https://api.cert.nabcommerce.com/2.0.18/SvcInfo
Secondary https://api.nabcommerce.com/2.0.18/SvcInfo

Certification Environment:
https://api.cert.nabcommerce.com/2.0.18/SvcInfo
REST
Primary https://api.nabcommerce.com/REST/2.0.18/SvcInfo

Certification Environment:
https://api.cert.nabcommerce.com/REST/2.0.18/SvcInfo
Secondary https://api.nabcommerce.com/REST/2.0.18/SvcInfo

Certification Environment:
https://api.cert.nabcommerce.com/REST/2.0.18/SvcInfo
Transaction Processing Endpoints
SOAP
Primary https://api.nabcommerce.com/2.0.18/Txn

Certification Environment:
https://api.cert.nabcommerce.com/2.0.18/Txn
Secondary https://api.nabcommerce.com/2.0.18/Txn

Certification Environment:
https://api.cert.nabcommerce.com/2.0.18/Txn
REST
Primary https://api.nabcommerce.com/REST/2.0.18/Txn

Certification Environment:
https://api.cert.nabcommerce.com/REST/2.0.18/Txn
Secondary https://api.nabcommerce.com/REST/2.0.18/Txn

Certification Environment:
https://api.cert.nabcommerce.com/REST/2.0.18/Txn

Commerce Web Services Endpoint URLs (where x.x.x represents the API version)

Figure 3 illustrates the relationship between the endpoint URLs for single merchant and multi-merchant applications. The secondary URLs have been omitted for brevity.

Figure 3: Accessing Web Service Endpoints

 


 

Getting Started

The following information is provided to help you get started with your CWS implementation. All web service endpoints provide metadata exchange via standard Web Service Description Language (WSDL) format.

The WSDL defines namespaces, data types, and operations. The WSDL and its XML formatted metadata are used by Integrated Development Environments (IDE) and proxy generation utilities to generate the proxy.

The following proxy generation utilities are available for Microsoft, Java, and PHP developers:

Contact your NAB Velocity Sales Engineer for sample applications for each of these development environments.

Proxy Generation

When generating proxies from the Commerce Web Services WSDL for the Service Information and Transaction Processing endpoints, many proxy generation tools will interpret lists (<>) as arrays ([ ]) by default.

For example, List<MerchantProfile> GetMerchantProfiles is generated as MerchantProfile[] GetMerchantProfiles. To generate lists specifically, be sure to configure your proxy generator accordingly.

To generate proxies, refer to the URLs below.

  • Service Information – https://api.cert.nabcommerce.com/2.0.18/SvcInfo
  • Transaction Processing – https://api.cert.nabcommerce.com/2.0.18/Txn

If you are not using a proxy generation tool, you can still build SOAP messages in the absence of a proxy. Please contact your NAB Velocity Sales Engineer for examples of the SOAP messages.

Viewing the WSDL

To view the Service Information and Transaction Processing WSDLs, refer to the URLs provided below.

Analyzing the Endpoint WSDL
Service Information Endpoint
https://api.cert.nabcommerce.com/2.0.18/SvcInfo?wsdl0 (Index 0 only)
https://api.cert.nabcommerce.com/2.0.18/SvcInfo?xsd0 (Index from 0 to 2)
Transaction Processing Endpoint
https://api.cert.nabcommerce.com/2.0.18/Txn?wsdl0 (Index 0 only)
https://api.cert.nabcommerce.com/2.0.18/Txn?xsd0 (Index from 0 to 5)

Analyzing the Endpoint WSDL

Note: Web service definition (wsdl=wsdl0) implements the XSD schemas (xsd=xsd0) which are the set of rules that the WSDL must follow. The WSDL defines the structure and format of the message, while the XSD defines the rules of the data types/values within the message.

Namespace and Type Name Conflicts

There are specific type names that are used in two different namespaces which may cause confusion during development. Because these type names are shared across namespaces, you can’t assign one to the other directly and they can’t be used interchangeably. As a result, you may be required to qualify the type name with the proper namespace.

The following type names exist in both the Service Information and Transaction Processing namespaces:

  • ApplicationLocation
  • CustomerPresent
  • EntryMode
  • HardwareType
  • IndustryType
  • PINCapability
  • ReadCapability
  • RequestACI
  • RequestAdvice
  • TypeISOCountryCodeA3
  • TypeISOCurrencyCodeA3
  • TypeISOLanguageCodeA3

For example, if you wish to use the Service Information TypeISOCountryCodeA3 type name:

com.nabcommerce.schemas.cws.v2_0.serviceinformation.TypeISOCountryCodeA3

To use the same type name in the Transaction Processing namespace, fully qualify the type name:

com.nabcommerce.schemas.cws.v2_0.transactions.TypeISOCountryCodeA3

For more information, contact your NAB Velocity Sales Engineer.

Comments