API Docs
The following information provides developers with an understanding of the “Preparing the Application to Transact” processes as they relate to the Service Information operations available in the Commerce Web Services SOAP/REST API, as well as the application workflows associated with each of these processes.
During the merchant activation process, transaction originators are issued a Service Key and credentials for authentication. At runtime, the payment application uses these credentials to authenticate to Commerce Web Services. Commerce Web Services currently supports token-based authentication credentials.
Note: Future releases of CWS will support username/password authentication credentials.
CWS utilizes the following two types of SAML (Security Assertion Markup Language) authentication tokens:
Identity tokens (identityToken) are signed authentication tokens provided to merchants or other transaction originators to prevent the unauthorized use of an application. Identity tokens are set to expire after 3 years, and therefore will require renewal.
Important! Identity tokens should be managed and protected in a manner consistent with current key management best practices which may include access control, encryption, or use of specialized security devices. Identity token owners are responsible for establishing practices for managing sensitive data like any other secure credential or business certificate.
Authentication credentials are used to authenticate to CWS by invoking the Service Information SignOnWithToken/SignOn operation and passing a valid identityToken. After successful authentication, a sessionToken is returned for use in all subsequent Service Information and Transaction Processing operations.
Identity tokens can be stored and secured in a file or database. Depending on the chosen storage method, access control and encryption considerations exist that are dependent upon the environment in which the application is running, as described below.
Storage Mechanism | Access Control Method | Encryption (Recommended) |
File | File system permissions | Whole disk encryption, file-based encryption, or application-specific encryption, such as Hardware Security Modules (HSM) to securely store and access identity tokens. |
Database | Database user permissions | Entire database encryption, single column encryption, or application-specific encryption. |
Methods of Securing Identity Tokens
If you plan to store the identity token string in a file, you are required to secure it using read-only file system permissions based on the user account under which the application is running. This applies to use cases applicable to third-party applications requiring installation and configuration on the application user’s desktop. Whether or not you choose to apply encryption on the entire file system or implement file-based or application-specific encryption will depend on the requirements of the application.
Best practices related to file system-based security of identity tokens include:
Another option for securing the identity token is to encrypt and store the identity token string in a database. This may be beneficial in use cases where the application resides in an environment that provides access via a hosted web solution.
Contact your NAB Velocity Sales Engineer for assistance in determining which method is most appropriate for your specific solution.
Session tokens (sessionToken) are “short-lived” tokens that are used to authenticate to CWS when invoking all Service Information and Transaction Processing operations after sign-on. Sessions tokens should only be stored in memory or cache for the life of the session or until expiration.
Session tokens expire 30 minutes after creation. When an expired session token is used to invoke an operation, CWS will return an ExpiredTokenFault, at which time the application should re-invoke the SignOnWithToken/SignOn operation and pass a valid identityToken to retrieve a new sessionToken.
Note: Applications should only request a new session token upon expiration of a previous session token. Requesting a new session token for every transaction will lead to processing delays in high transaction volume applications. As a best practice, the application should renew its session token only if older than 25minutes. The application should also have fault handling to perform a refresh if an “ExpiredTokenFault” is received.
The authentication process is illustrated below.
Figure 7: The Sign-On Authentication Process
The next step in preparing the application to transact is to retrieve, update (if necessary), and save the appropriate characteristics and configuration information associated with your payment-enabled application. This configuration data includes information such as application name, application version, PTLS Socket ID, and additional capabilities of the application.
Note: This is a one-time event that should be performed upon initial installation or launch of the application.
The process of Managing Application Configuration Data is illustrated below.
Figure 8: Managing Application Configuration Data
Note: Invoking the GetApplicationData operation with an invalid applicationProfileId will generate a general CWSFault.
After Managing Application Configuration Data, the application can retrieve service information which defines the transaction processing operations available to their Service Key.
One of the most important steps of the Preparing the Application to Transact implementation process is the retrieval of Service Information (Step 3). Service Information is retrieved by invoking the GetServiceInformation operation. Service Information is comprised of the following:
The GetServiceInformation operation returns the ServiceInformation object which inherits the following child objects:
Note: The response elements contained in the ServiceInformation object can be stored in memory and referenced when initiating payment processing requests with any one of the services supported.
The information returned to the application in the ServiceInformation object can be used to dynamically drive application logic. For example, the ServiceInformation object returns a list of CWS operations supported for each Service Key. Depending on the supported operations, application logic can be written to drive the presentation of UI elements unique to a specific service or other drive other application functionality. This is especially useful to software companies developing applications that support multiple services and multiple merchants.
Consider the following diagram illustrating the relationship between serviceId and workflowId:
While it is possible for a single Service Key to support multiple services (by serviceId), support for transaction workflows returns both a serviceId and a workflowId. The workflowId represents a collection of supported payment services and value-added services, as well as the order in which each should be invoked during the transaction workflow.
Note: When supporting workflows, the workflowId must be passed in each subsequent transaction processing request to trigger workflow processing. When workflows are not being supported (or workflow processing is simply not desired), the appropriate serviceId should be passed. Refer to Understanding Workflows for more information.
Once the application receives the session token from CWS, it must retrieve Service Information to determine what services have been authorized for the specific Service Key.
Service Information is retrieved by invoking the GetServiceInformation operation which returns the following information to the application:
The process of retrieving Service Information is illustrated below.
Figure 9: Retrieving Service Information
Once Service Information has been retrieved, the application can begin managing one or more Merchant Profiles.
In order to successfully process transactions, specific data elements are required by each service provider. The number of required data elements varies by service provider and the payment services offered. In addition, some of this data is unique to each transaction while other data elements are “common” to all transactions.
Merchants must save this commonly used data in the Platform database. During transaction processing operations, this data is included in each transaction request message sent to the service provider. This data store, or “library”, of commonly used data is referred to as common configuration data.
There are two types of common configuration data that can be stored for inclusion in all transaction request messages—Merchant Data and Transaction Data.
By combining each of these common configuration data types with payment-specific data such as card information, cardholder account number, and transaction amount, a complete transaction request message can be successfully constructed.
Common configuration data is stored on behalf of each merchant based on a unique Merchant Profile. When invoking transaction processing operations, Merchant Profiles are accessed to ensure all required common configuration data elements are sent with the transaction. Applications can check to see whether specific Merchant Profiles have been initialized (saved at least once). If saved, Merchant Profiles can be retrieved for validation, display, or modification.
While default common configuration data values are stored with the Merchant Profile, values that are explicitly set in a transaction will override the default data values stored in the Merchant Profile. If such data values are not explicitly set in the transaction, the default values stored in the Merchant Profile are used.
Merchant Profiles are associated with a specific service ID and transaction class. If a Service Key supports multiple transaction types within a transaction class, the Merchant Profile will automatically be copied to all other transaction classes. For example, if the Bankcard service is available, supporting Credit and PIN Debit requires a unique Merchant Profile for both Credit and PIN Debit services.
Ultimately, the application workflow associated with the management of common configuration data depends on whether you are developing a single-merchant application or a multi-merchant application.
For more information about the specific operations associated with the management of Merchant Profiles, refer to Managing Merchant Profiles.
Integration Tip! Merchant Profiles are required by payment service providers to process transactions. While Merchant Profiles can be be created and managed programmatically within the application, leveraging the Merchant Profile Management within Commerce Link allows you to manage profile data in a hosted interface while reducing integration times. Contact us for more information.
Payment applications designed to be used by a single merchant using a single Service Key are typically desktop applications that must be installed and configured on an individual basis, or hosted web applications that are designed to be used by a single merchant. In either case, Commerce Web Services requires that single-merchant applications store common configuration data in the Platform database.
In a single-merchant application, there is only one Merchant Profile associated with a single Service Key. When invoking the GetMerchantProfile operation, the application passes an empty merchantProfileId which retrieves a “default” (empty) MerchantData object for that merchant Service Key. This empty MerchantData object must then be updated by the application, and a new merchantProfileId must be saved at this time.
Note: In a single-merchant application implementation, there is no advantage to separating administrative functionality from transaction processing functionality since only one Merchant Profile will ever be associated with the Service Key.
The workflow for single-merchant applications is illustrated below.
Figure 10: Managing Common Configuration Data – Single-Merchant Application Workflow
If a merchantProfileId is not passed (or an invalid merchantProfileId is provided) a new default MerchantData object is created and returned to the application allowing updates to Merchant Profile data.
If a new default MerchantData object was returned by GetMerchantProfile, a new merchantProfileId must be created and saved at this time.
Multi-merchant payment applications are designed to be used by multiple merchants using a single Service Key. These applications are typically web applications, but they can also be applications that allow multiple merchants to use one physical terminal. In these use cases, the transaction originator associated with the Service Key is processing on behalf of each merchant, much like a SAAS (Software as a Service) offering.
Like single-merchant applications, Commerce Web Services requires that multi-merchant applications store common configuration data in the Platform database. Because multi-merchant applications require the storage of multiple, unique sets of common configuration data, the workflow associated with the retrieval and update of common configuration data must be handled on a per-merchant basis by explicitly passing a merchantProfileId in the transaction request message.
When there are multiple merchants under a single Service Key, multiple profiles are retrieved by invoking the GetMerchantProfileIds operation. This allows the application to display a list of all Merchant Profiles associated with a specific Service Key. A specific Merchant Profile can then be retrieved by calling the GetMerchantProfile operation.
Note: In a multi-merchant application implementation, the separation of administrative functionality from transaction processing functionality is advantageous. This allows the application to have a common interface for managing multiple Merchant Profiles associated with a single Service Key.
Because common configuration data contains information that is specific to each merchant, when the application supports multiple merchants using a single Service Key, the application must first check to see if common configuration data has been saved for a specific merchantProfileId by invoking the IsMerchantProfileInitialized operation each time the application is launched.
The workflow for multi-merchant applications is illustrated below.
Figure 11: Managing Common Configuration Data – Multi-Merchant Application Workflow
If the requested merchantProfileId is found, the application is ready to transact and no further updates to the Merchant Profile are required.
Once a list of Merchant Profiles have been returned, a specific profile can be updated by invoking the GetMerchantProfile operation and passing the desired merchantProfileId to be retrieved for update.
A MerchantData object is returned to the application containing all common configuration data associated with the provided merchantProfileId.
The following Service Information operation flows describe the typical order in which specific operations are invoked to properly authenticate and configure applications during the Preparing the Application to Transact process:
Implementation Step | Operation Flows | |
Step 1: Sign-On Authentication | SignOnWithToken/SigonOn | |
Step 2: Managing Application Configuration Data | SaveApplicationData > GetApplicationData > DeleteApplicationData | |
Step 3: Retrieving Service Information | GetServiceInformation | |
Step 4: Managing Merchant Profiles | Add Merchant Profile | SaveMerchantProfiles > GetMerchantProfileIds |
Update Merchant Profile | GetMerchantProfileIds > GetMerchantProfile > SaveMerchantProfiles | |
Delete Merchant Profile | GetMerchantProfileIds > DeleteMerchantProfile | |
Verify Merchant Profile | GetMerchantProfileIds > IsMerchantProfileInitialized | |
Validate Merchant Profile | ValidateMerchantProfile Note: SaveMerchantProfiles performs the same function. |
Contact your NAB Velocity Sales Engineer for additional guidance regarding the most appropriate operation flows for your payment solution.
Updated: June 2, 2017
SUBMIT A DEVELOPER SUPPORT REQUEST
Agent or a merchant? Contact NAB support at 866.485.8999 EXT 2341