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 open_in_newhttps://localhost:9790/rest/commandLink opens new window.
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 aremethod
-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.
note
The current request stops until you respond with a continue or cancel message.
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:
Connect your card reader and terminal to the computer.
Close all open applications and browsers.
Double-click
CommerceWebServicesSetup.exe
. The Commerce Web Service installation wizard appears.On the Welcome to CommerceWebServices Setup wizard page, click Next.
On the Choose Install Location wizard page, select the Destination Folder then click Install.
On the Installation Complete wizard page, click Next.
On the Completing CommerceWebServices Setup wizard page, click Finish.
After 30 to 45 seconds, find the ConvergeConnect icon from the system tray.
Right-click the icon and click Show… to open the ConvergeConnect Status window.
Confirm that:
- Service and CWS show Running.
- Port shows 9790.
- The values of Reader and Printer match the hardware you connected in Step 1.
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.
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
}
}
Configure CWS Log Level
Starting with CommerceSDK release 4.6.0, you have the option to configure the CWS log level to output DEBUG and TRACE logging. Note that this feature should not be turned on by default. You should only configure the log level to DEBUG or TRACE when you need to diagnose a problem and send CWS logs to product support.
Below you will find the specific API method for setting the CWS log level. Note that the log level can also be configured via the openPaymentGateway method by passing “logLevel” as one of the parameters.
Request
Method | Description |
---|---|
method string | required | setLogLevel |
requestId string | required | Request ID |
targetType string | required | api |
parameters JSONObject | required | All relevant parameters for CWS log level. |
logLevel string | required | CWS log level Valid values:
|
Response
Method | Description |
---|---|
requestId string | Request ID As specified in the request. |
statusDetails string | Request Status |
data JSONObject | Object holding various responses. |
completed boolean | Request Result Valid values:
|
logLevel string | The log level that was set. |
Request
{
"method" : "setLogLevel",
"requestId" : "1253881538",
"targetType" : "api",
"parameters" : {
"logLevel" : "DEBUG"
}
}
Response
{
"requestId" : "1253881538",
"statusDetails" : "REQUEST_ACCEPTED",
"data" : {
"logLevel" : "DEBUG",
"completed" : true
}
}
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 or UPP pinpad during a transaction. |
overrideDebitNetworkPreferences | This method overrides the US debit network preference used on an RBA or UPP pinpad during a transaction. |
overrideCvmOptions | This method overrides CVM options such as signature for card transactions. |
setDeviceConnectionConfiguration | This method sets the connection configuration to specify which types of devices to search for. |
getDeviceConnectionConfiguration | This method returns the current connection configuration. |
setTransactionLaneNumber | This method specifies the lane number where transactions are performed. |
setLogLevel | This method sets the CWS log level. |
getLogLevel | This method returns the current log level. |