Transaction Management Service Overview

The Transaction Management Service (TMS) provides read-only access to merchant transaction data stored in the Commerce Web Services (CWS) transaction database. TMS eliminates the need for the merchant application to store transaction data locally by providing access to merchant transaction data for transaction reporting purposes, as well as for processing subsequent transactions, such as incremental authorizations, settlement, etc.

Software companies can take advantage of this value-added service through the integration of the Transaction Management Service API. The TMS API makes use of both Service Key and sign-on authentication credentials to ensure safe, secure access to transaction data.

TMS provides the following benefits:

  • Access to all Bankcard transaction data – All Bankcard Transaction Classes and Types are accessible.
  • Two levels of transaction detail – On a per query basis, you can specify whether summary or detailed transaction information should be retrieved. Transaction detail data is returned in PTLS XML format for all users and CWS XML format for CWS-initiated transactions.
  • Variety of search/filter criteria – Enables greater precision and faster response times by limiting the data returned to only that which is required.
  • Identification of Transaction Families – Authorizations or Returns followed by subsequent transactions are linked using a parent ID. This allows all related transaction data to be returned in the context of the entire transaction family.

Note: The integration of transaction management functionality is based on the existing CWS SOAP/REST APIs. For more information about integrating the CWS SOAP/REST APIs, refer to the Commerce Web Services Developer’s Guide.

 


 

Component Architecture

The Transaction Management Service requires a dedicated web service endpoint to reduce the impact to existing CWS SOAP/REST endpoints during large query operations.

Due to the large amount of stored transaction data, response data is retrieved in manageable "chunks" when performing transaction data queries. This allows the application to easily manage the data for proper paging display.

By default, up to 50 transaction records are returned as part of a single query response. This default can be overridden by the client by any amount that does not exceed the maximum record return count. If the client request exceeds the maximum configurable value, an error message is returned to the application indicating the maximum value of records that can be returned has been exceeded.

The high-level Transaction Management Service architecture is illustrated below.

Figure 1: Component Architecture – Transaction Management Service

 


 

Web Service Endpoints

In addition to the Service Information (SvcInfo) and Transaction Processing (Txn) service endpoints provided by CWS integrations, the Transaction Management Service uses a dedicated web service endpoint called TMS.

The Transaction Management Service web service endpoint and its supported functions are illustrated below:

Figure 2: Transaction Management Web Service Endpoints

Transaction Management Endpoints

Transaction Management (TMS) endpoints provide the following functionality:

  • Ability to query for Commerce Web Services (CWS) transactions for reporting purposes, as well as for processing subsequent transactions, such as incremental authorizations, settlement, etc.

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.

Transaction Management Endpoint URLs
SOAP
Primary https://api.cert.nabcommerce.com/2.0.18/DataServices/TMS
Secondary https://api.cert.nabcommerce.com/2.0.18/DataServices/TMS
REST
Primary https://api.cert.nabcommerce.com/REST/2.0.18/DataServices/TMS
Secondary https://api.cert.nabcommerce.com/REST/2.0.18/DataServices/TMS

Transaction Management Endpoint URLs (where x.x.x represents the API version)

Figure 3 illustrates the relationship between the endpoint URLs and the Transaction Management endpoints. The secondary URLs have been omitted for brevity.

Figure 3: Accessing TMS Web Service Endpoints

Comments