Commerce Web Services

Manage 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 provider and the payment services offered. Some of the data is unique to each transaction, while other data elements are “common” to all transactions.

Merchants must save commonly used data in the Platform database. During transaction processing operations, the data is included in each transaction request message sent to the service provider. The data store (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: 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 & 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. The applications can validate 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 explicitly set in a transaction override the default data values stored in the Merchant Profile. If the data values are not explicitly set in the transaction, the default values 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 is automatically copied to all other transaction classes, (e.g.: Bankcard service is available, supporting Credit and PIN Debit requires a unique Merchant Profile for both Credit and PIN Debit services).

The application workflow associated with the management of common configuration data depends on the development of a single-merchant application or a multi-merchant application.

Single Merchant Applications

Payment applications designed for a single merchant using a single Service Key are typically desktop applications installed and configured on an individual basis or hosted web applications. In either case, CWS requires single-merchant applications to 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 GetMerchantProfileoperation, the application passes an empty merchantProfileId to retrieve a “default” (empty) MerchantData object for that merchant Service Key. The empty MerchantData object must be updated by the application and a new merchantProfileId saved.

Note: In a single-merchant application implementation, there is no advantage to separating administrative functionality from transaction processing functionality since only one Merchant Profile is associated with the Service Key.

The workflow for the initial launch of a single-merchant application:

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.
If a merchantProfileId is passed with the request, a MerchantData object is returned to the application containing all common configuration data associated with the merchantProfileId provided.

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.

Save Merchant Profile – The merchant updates common configuration data (as necessary) and invokes the SaveMerchantProfilesoperation to save. If a new default MerchantData object is returned by GetMerchantProfile, a new merchantProfileId must be created and saved at this time.Subsequent launch of a single-merchant application workflow:
Verify Merchant Profile – On subsequent launch of the application, the IsMerchantProfileInitialized operation is invoked to verify common configuration data for the specific merchantProfileId is saved.
If common configuration data is found for the merchantProfileId provided, 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 tied to a single Service Key. The applications are typically web applications, but can also be applications allowing multiple merchants to use one physical terminal. In this 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.

CWS requires 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 multiple merchants are 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 be retrieved by calling the GetMerchantProfile operation.

Note: In a multi-merchant implementation, the separation of administrative functionality from transaction processing functionality is advantageous by allowing the application to have a common interface for managing multiple Merchant Profiles under a single Service Key.

Because common configuration data contains information specific to each merchant, when multiple merchants are supported using a single Service Key, the application must verify common configuration data is saved for a specific merchantProfileId by invoking the IsMerchantProfileInitialized operation each time the application is launched.

The workflow for multi-merchant applications is:

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

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

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 is returned, a specific profile can be updated by invoking the GetMerchantProfile operation and passing the desired merchantProfileId. A MerchantData object is returned to the application containing all common configuration data associated with the merchantProfileId provided.
Save Merchant Profile – The application updates the configuration data as necessary and invokes the SaveMerchantProfiles operation to save.

Integration Tip! Merchant Profiles are required by payment service providers to process transactions. While Merchant Profiles can be created and managed 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.

Best Practices

Below are some recommendations and best practices associated with the integration of the Preparing the Application to Transact operations:

As a performance consideration, you may chose to develop a separate application that is used for all administrative functions, such as Retrieving Service Information, Managing Application Configuration Data, and Managing Merchant Profiles. This is particularly useful when developing multi-merchant applications.
Retrieving Service Information and Merchant Profile Data should only be performed as an initial setup procedure and not with each subsequent transaction.
As a best practice, serviceId, applicationProfileId, and merchantProfileId should be stored during the Preparing the Application to Transact process, rather than performing a value lookup for every transaction.
As a best practice, the application should track the time duration of the sessionToken. Prior to processing transactions, the application should reference the age of the current sessionToken. If the value is greater than 25 minutes, a new call to SignOn should be made and the process of tracking the sessionToken repeated.
After completing the steps above, it is recommended that the serviceId, applicationProfileId, and merchantProfileId be encrypted and stored in the same manner as the identityToken.

API Reference

For Service Information API reference information, click on the links below: