Velocity Developer Resources

API DOCS MENU

Service Information

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.

 

---

 

Sign-On Authentication

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
• Session Tokens

Identity 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.

Securing Identity Tokens

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:

• Setting file permissions so that only the following users can read or write to the file storing the identity token:
  • Authorized administrative users
  • The service user account under which the application is running
• Ensuring that only authorized administrator users of the application can call operations that read or write to the file storing the identity token.
• Ensuring that you have IT policies and procedures in place to enforce and monitor the protection of the file storing the identity token.
• If your customers are operating, managing, deploying, or otherwise have access to machines storing identity tokens, ensure that you document (and train if applicable) the policies and procedures that your customers need to follow to protect such tokens.
• Notifying your NAB Velocity Sales Engineer immediately if you believe the identity token has been compromised.

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

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

1. During the merchant activation process, the merchant is assigned an identity token.
2. The identity token is provided to the application administrator where it is embedded into the application for use during application sign-on authentication.
3. The SignOnWithToken/SignOn operation is invoked during initial application sign-on to validate the identity token established during the merchant activation process.
4. Once the identity token is validated by the Token Service, a session token is returned to the application.

 

---

 

Managing Application Configuration Data

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

1. Implementation Support will provide the application administrator with a unique PTLS Socket ID as the result of the Application Certification process. This PTLS Socket ID is embedded into the application. Contact your NAB Velocity Sales Engineer for a PTLS Socket ID to use for application testing purposes.
2. Get Application Data – The application invokes the GetApplicationData operation and passes an applicationProfileId in the request.
3. An ApplicationData object is returned to the application, allowing the merchant to update their application configuration data as necessary.
4. Save Application Data – The SaveApplicationData operation is invoked to save updates to application configuration data. The embedded PTLS Socket ID is passed with the request as part of the ApplicationData object.
5. An applicationProfileId is generated based on the PTLS Socket ID provided and is returned to the application where it must be stored securely and recalled in session cache for use in all subsequent transactions. Refer to Sign-On Authentication for specific recommendations.

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.

 

---

 

Understanding Service Information

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:

• Payment services supported by the application, such as Credit, PIN Debit, and/or ACH services.
• CWS operations supported, such as Authorize, Undo, Capture, etc.
• Specific payment service features supported by the destination service provider.
• Specific Platform workflows supported by the Service Key.

The ServiceInformation Object

The GetServiceInformation operation returns the ServiceInformation object which inherits the following child objects:

• BankcardService – Contains information about the Bankcard service(s) for which it is configured, such as serviceId, the Transaction Processing operations supported, support for Address Verification (AVS), Purchase Card Level 2/3 data, and the specific tenders supported by the service.
• ElectronicCheckingService – Contains information about the Electronic Checking service(s) for which it is configured, such as serviceId, the transaction processing operations supported, and the specific tenders supported by the service.
• StoredValueService – Contains information about the Stored Value service(s) for which it is configured, such as serviceId, the transaction processing operations supported, and the specific tenders supported by the service.
• Workflow – Contains information about the Platform Workflows supported by the application’s Service Key.

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.

Driving Application Logic based on Service Information

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.

Service Information serviceId vs. workflowId

Consider the following diagram illustrating the relationship between serviceId and workflowId:

1. The GetServiceInformation operation is invoked against the CWS Service Information Service (SIS) endpoint.
2. The ServiceInformation object is returned containing the services (by serviceId) supported by the requesting application’s Service Key/identityToken.

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.

Retrieving Service 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:

• Payment services available, such as Credit, PIN Debit, and/or ACH services.
• Operations supported, such as payment account verification, authorize and capture, etc.
• Payment service features supported.
• Specific transaction workflows supported by the Service Key.

The process of retrieving Service Information is illustrated below.

Figure 9: Retrieving Service Information

1. Get Service Information – The application invokes the GetServiceInformation operation which passes the sessionToken to the Service Information endpoint to initiate a request for all Service Information associated with the merchant Service Key.
2. All Service Information is returned to the application, which defines the services, workflows, and transaction processing operations available to their Service Key.

Once Service Information has been retrieved, the application can begin managing one or more Merchant Profiles.

 

---

 

Managing 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.

• Merchant Data – Data specific to the merchant, such as merchant name, address, and merchant ID.
• Transaction Data – Data that does not change from transaction to transaction, such as CustomerPresent flags and Currency Codes.

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 and Merchant Profiles

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.

Single-Merchant Applications

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

Initial Launch of Application

1. Get Merchant Profile – The application invokes the GetMerchantProfile operation to ensure the application prompts for the completion of common configuration data before being able to transact.
2. If a merchantProfileId is passed with the request, a MerchantData object is returned to the application containing all common configuration data associated with the provided merchantProfileId.

   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.

3. Save Merchant Profile – The merchant updates common configuration data (as necessary) and invokes the SaveMerchantProfiles operation to save the new configuration data for the Merchant Profile.

   If a new default MerchantData object was returned by GetMerchantProfile, a new merchantProfileId must be created and saved at this time.

   Subsequent Launch of Application

4. Verify Merchant Profile – On subsequent launch of the application, the IsMerchantProfileInitialized operation is invoked to verify that common configuration data for the specific merchantProfileId has been saved.
5. If common configuration data is found for the provided merchantProfileId, the application receives a boolean value of “true” and is ready to transact.

Multi-Merchant Applications

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

1. Verify Merchant Profile – The IsMerchantProfileInitialized operation is invoked invoked to verify that common configuration data for the specific merchantProfileId has been saved.

   If the requested merchantProfileId is found, the application is ready to transact and no further updates to the Merchant Profile are required.

2. Get Merchant Profile – Optional: If updates to Merchant Profiles are necessary, the GetMerchantProfileIds operation is invoked to retrieve a list of all saved merchantProfileId‘s.

   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.

3. Save Merchant Profile – The application updates this configuration data as necessary and invokes the SaveMerchantProfiles operation to save the new configuration data.

 

---

 

Operation Flows

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