Commerce Web Services

Commerce Web Services (CWS) provides an HTTP API in the form of a web server that runs on the same workstation to which the payment terminal (card reader) and printer are connected.

In this topic:

Request and Response Model

CWS uses a request-response model based on the concept of Polling. Elavon recommends a polling rate of 750ms or higher.

When you send a request, a response returns confirming that CWS received the request and is processing it. From that point on, CWS polls periodically to ask for the status of your request.

For example, when running a startPaymentTransaction request, CWS polls with getPaymentTransactionStatus. While polling, you may receive updated progress status messages for long-running processes.

Response messages contain a completed parameters that reads as false  until CWS finishes processing the request. Once the completed parameter is set to true,  stop polling and read the transaction request results.

Endpoint

Services are requested via HTTP POST with request and response payload in JSON format to https://localhost:9790/rest/command.

Request and Response Structures

The core properties that define a CWS transaction request are:

  • method - This indicates the service to be performed.
  • targetType - This indicates the type of request.
  • requestId - This is the unique identifier for tracking the request.
  • parameters - These are method-dependent properties detailing the specifics of the request.

The core properties that define a CWS transaction response are:

  • completed - Indicates whether CWS has finished processing the transaction.
  • chanId - Used to obtain status, and continue or cancel the current transaction.
  • eventQueue - Lists the events the occurred and its corresponding timestamps.

Callbacks

Commerce SDK uses callbacks in a response to ask for additional information.

When you receive a callback, the completed flag is false,  and there is a requiredInformation property detailing the request for more information.

error_outline
note

The current request stops until you respond with a continue or cancel message.

Target Types and Methods

The main target types (targetType) that CWS provides are as follows:

  • paymentGatewayConverge - This type of request post transactions to Converge.
  • cardReader - This type of request changes card reader settings or runs card reader tasks.
  • printer - This type of request prints receipts through the connected printer.
  • api - This type of request retrieves device and/or environment information or overrides default debit network and language settings.

paymentGatewayConverge

This table describes the methods of the paymentGatewayConverge target type.

Method Description
openPaymentGateway This method sends your Converge credentials to CWS.
Refer to the Installation - Send Converge Credentials section for more information.
startPaymentTransaction This method integrates a payment transaction into your application.
This method is applicable to these transaction types: Sale, Auth Only, Convert Auth to Sale, Auth Only Reversal, Void and Stand Alone Refund
cancelPaymentTransaction This method integrates a payment cancellation transaction into your application.
This method is applicable to Cancel Transaction.
searchPaymentTransaction This method integrates a lookup of previous transactions into your application.
This method is applicable to Transaction Lookup.
linkedRefund This method integrates a linked refund to a cardholder's payment card into your application.
This method is applicable to the Linked Refund transaction type.
printReceipt This method integrates receipt printing into your application for a previous transaction or a historical transaction when the transactionId is present.
emailReceipt This method integrates email sending into your application for a previous transaction or a historical transaction when the transactionId is present.
fileReceipt This method integrates receipt saving into your application for a previous transaction or a historical transaction when the transactionId is present. CWS saves the receipt in the logs folder.
getPaymentTransactionStatus This method integrates polling of status for the currently running transaction into your application.
continuePaymentTransaction This method integrates the continuance of transaction processing into your application.
This method is applicable to Continue Transaction.

cardReader

This table describes the methods of the cardReader target type.

Method Description
startCardReaderConfiguration This method sets the IP connection criteria for the card reader.
getCommandStatusOnCardReader This is the polling method for all cardReader methods.
startCardReadersSearch This method locates devices when starting your first transaction.
getCardReadersSearchStatus This method retrieves the device search status.
startCardReadOnCardReader This method perform an encrypted card read from a magnetic stripe card and returns the encrypted card data without the need for a Sale or Authorization transaction.
startPinEntryOnCardReader This method directs the card reader to request for a PIN entry.
startResetOnCardReader This method returns the pinpad to the original welcome screen prior to an authorization.
setDailyRebootTimeOnCardReader This method reboots a PCI V4 pinpad after 24 hours of continuous running time.
startDeviceStatusOnCardReader This method retrieves the connection status, battery charging status and battery charge level of the pinpad device.
startRebootOnCardReader This method triggers the reboot of the card reader.
startAmountConfirmationOnCardReader This method triggers the card reader to prompt the customer to confirm or cancel the displayed amount.
startSignatureCaptureOnCardReader This method triggers the card reader to prompt the customer to submit a signature.

printer

This table describes the methods of the printer target type. Use these methods to print custom content on the receipt.

Method Description
startPrintReceiptOnPrinter This method controls the content printed on the receipt.
continuePrintReceiptOnPrinter This method continues the printing of the receipt if startPrintReceiptOnPrinter requires more information.
cancelPrintReceiptOnPrinter This method cancels the printing of the receipt.
getPrintReceiptStatusOnPrinter This method polls the receipt print status.

api

This table describes the methods of the api target type.

Method Description
getApiInfo This method retrieves the names and version numbers of various Commerce SDK modules.
setPreferences This method configures custom card reader and printer settings.
getVersionInfo This method returns the name and version numbers of various Commerce SDK modules currently in use.
getEnvironmentInfo This method returns details about the modules in use and runtime environment information about the platform.
getCardReaderInfo This method retrieves information about the connected card reader.
getPrinterInfo This method returns the printer name and online status.
overrideDefaultTerminalLanguage This method overrides the language used on an RBA pinpad during a transaction.
overrideDebitNetworkPreferences This method overrides the US debit network preference used on an RBA pinpad during a transaction.

Installation

The CWS installer is a Windows desktop application bundle that includes the following components:

  • Commerce SDK
  • Commerce Web Services
  • Card Reader Drivers
  • Printer Drivers
  • System Tray-accessible Application (for CWS health monitoring)

In this section:

Windows Operating Systems

You can only install CWS on Windows 7, 8, 8.1 and 10.

Install CWS

To install CWS, complete the following steps:

  1. Connect your card reader and terminal to the computer.
  2. Close all open applications and browsers.
  3. Double-click CommerceWebServicesSetup.exe. The Commerce Web Service installation wizard appears.
  4. On the Welcome to CommerceWebServices Setup  wizard page, click Next.
  5. On the Choose Install Location  wizard page, select the Destination Folder then click Install.
  6. On the Installation Complete  wizard page, click Next.
  7. On the Completing CommerceWebServices Setup  wizard page, click Finish.
  8. After 30 to 45 seconds, find the ConvergeConnect icon from the system tray.
  9. Right-click the icon and click Show... to open the ConvergeConnect Status window.
  10. Confirm that Service and CWS show Running.

    Confirm that Port shows 9790.

    Confirm that the values of Reader and Printer match the hardware you connected in Step 1.

error_outline
note
  • CWS and ConvergeConnect start automatically when the computer boots up.
  • In such instances, run the CWS application or service as an administrator. The service will not run otherwise.
  • If outbound requests must go through a proxy on your network, make sure to select the Bypass proxy server for local addresses option from the Windows system proxy settings. You may also need to access the Advanced settings and add an Exception for  localhost.

Post Installation Verification

To verify that CWs is working properly, send a getEnvironmentInfo request with a header for Content-Type of application/json.

error_outline
note

You can use curl or a browser plugin like HttpRequester or Postman.

Example

Request
{
  "method" : "getEnvironmentInfo",
  "requestId" : "d002edbd-010a-4c51-8407-f14b80c49bf4",
  "targetType" : "api",
  "version" : "1.0"
}
Response
{
    "requestId": "d002edbd-010a-4c51-8407-f14b80c49bf4",
    "statusDetails": "REQUEST_ACCEPTED",
    "data": {
        "cwsInfo": {
            "name": "commerce-web-services",
            "version": "..."
        },
        "conconInfo": {
            "name": "converge-connect",
            "version": "..."
        },
        "comsdkInfo": {
            "componentVersions": [
                {
                    "name": "commerce-core",
                    "version": "..."
                },
                {
                    "name": "commerce-converge",
                    "version": "..."
                },
                {
                    "name": "commerce-desktop-converge",
                    "version": "..."
                },
                {
                    "name": "ingenico-rba",
                    "version": "..."
                },
                {
                    "name": "ingenico-rba-wrapper",
                    "version": "..."
                },
                {
                    "name": "RBA",
                    "version": "..."
                },
                {
                    "name": "StarMicronics Printer",
                    "version": "..."
                }
            ],
            "runtimeInformation": [
                {
                    "name": "os.arch",
                    "value": "..."
                },
                {
                    "name": "os.name",
                    "value": "..."
                },
                {
                    "name": "os.version",
                    "value": "..."
                },
                {
                    "name": "java.version",
                    "value": "..."
                },
                {
                    "name": "java.vendor",
                    "value": "..."
                }
            ]
        },
        "completed": true
    }
}