Elavon downloads and stores cookies on your device when you visit our website. We use these cookies to better understand and improve your browsing experience by identifying most visited pages, personalising content, and measuring site performance.

Essential cookies enable core functionality such as page navigation and access to secure areas. The website cannot function properly without these cookies; they can only be disabled by changing your browser preferences.

These are cookies that support site functionality that is visible or advantageous to you or your experience of the site, they enable websites to remember choices and provide a more personalized experience.   Functional cookies help to provide services that you request, such as language preference or layout.

Performance cookies help us to improve our website by collecting and reporting information on its usage (for example, which of our pages are most frequently visited).

These cookies and similar technologies gather information about your browsing habits. They remember that you've visited a website and share this information with other organisations, such as advertisers and platforms on which we advertise. They do this in order to provide you with ads that are more relevant to you and your interests. Although these cookies and similar technologies can track your visits to other websites, they don't usually know who you are. Without these cookies, online advertisements you encounter will be less relevant to you and your interests.

Cookie Settings

U.S. Bank Europe DAC. Registered in Ireland – Number 418442..  Registered Office: Block F1, Cherrywood Business Park, Dublin 18, D18 W2X7, Ireland.
U.S. Bank Europe DAC, trading as Elavon Merchant Services, is regulated by the Central Bank of Ireland.
 
U.S. Bank Europe DAC. Registered in Ireland with Companies Registration Office. The liability of the member is limited. United Kingdom branch registered in England and Wales under the number BR022122.
U.S. Bank Europe DAC, trading as Elavon Merchant Services, is a credit institution authorised and regulated by the Central Bank of Ireland.  Authorised by the Prudential Regulation Authority.  Subject to regulation by the Financial Conduct Authority and limited regulation by the Prudential Regulation Authority.  Details about the extent of our regulation by the Prudential Regulation Authority are available from us on request.

Most popular solutions

Additional solutions

Fusebox integration & options

Optional platform features

Documentation

North America

Europe

Regions

## Prerequisites

Before you get started, make sure to install the following:

- Visual Studio 2013 or later
- .NET Framework 4.5.2 or later
- :magic-link[Commerce Web Services]{id="cws"}

## Proxy configuration

In order to process transactions, Commerce SDK needs to be able to make outbound internet calls to the Converge payment gateway. If the Windows workstations running Commerce SDK are required to send internet traffic through a network proxy, you have a couple of options. You can either bypass the proxy or configure Commerce SDK proxy support.


### Proxy bypass

This will enable the workstations to access Converge directly without going through the proxy. Request your network administrator to add the following Converge addresses/IPs to a proxy bypass whitelist:

- `api.convergepay.com`
- `api.demo.convergepay.com`

No further Commerce SDK configuration is required.

### Commerce SDK proxy configuration

To configure the proxy for Commerce SDK, pass the proxy information and use `validateAccount` to test if Commerce SDK can communicate with Converge.

| Configuration | Description |
| ---- | ---- |
| proxyAddress required | Proxy address |
| proxyPort required | Proxy port number |
| proxyUser optional | Proxy user The username for proxy authentication (where applicable). |
| proxyPassword optional | Proxy password The password for proxy authentication (where applicable). |

:::::notice{important}

Commerce SDK returns errors in the `validateAccount` callback and the commerce web services may provide more information.

If you cannot configure the proxy environment, you must use the proxy bypass method.
:::::


### Example

```c#
OpenPaymentArgs obea = new OpenPaymentArgs(); 

....

ProxyInfo proxyInfo = null;
String proxyAddress = null;
String proxyPort = null;
String proxyUser = null;
String proxyPassword = null;

if (!(null == (temp = pf.get("proxyAddress"))))
 proxyAddress = temp;
if (!(null == (temp = pf.get("proxyPort"))))
 proxyPort = temp;
if (!(null == (temp = pf.get("proxyUser"))))
 proxyUser = temp;
if (!(null == (temp = pf.get("proxyPassword"))))
 proxyPassword = temp;

// address and port are required attributes
// user and password should only be populated if the proxy server requires them
if (proxyAddress != null && proxyPort != null)
 proxyInfo = new ProxyInfo(proxyAddress, proxyPort, proxyUser, proxyPassword);

obea.proxyInfo = proxyInfo;

OpenPaymentGatewayResults tr = m_CWS.OpenPaymentGateway(obea, null);
MyOpenPaymentGatewayComplete(tr);

...

```

## Build the sample application

1. Copy and extract the `CSharpSrc.zip` file.

 There are two sample apps to choose from:

 - **SalesApp** is a simple app that focuses on basic functionality
 - **TransApp** explores all the available features in CSDK

2. In Visual Studio, go to **File/Open/Project/Solution** and choose `SalesApp.sln` or `TransApp.sln`.
3. You are set to start building and debugging the sample application.

 
 :::::notice{note}

 You may need to remove and re-add the `CWSWrapper` DLL files in your project's References section.
 
 :::::


### Converge credentials

1. Open the `CWSTransApp.properties` file in the `CWSApp\CWSTransApp` directory.
2. Uncomment these lines and add your information.

 ```c#
 # serverType=DEMO
 # pin=demo_pin
 # user=demo_userId
 # merchant=demo_merchantId
 # vendorId=your_vendorId
 # vendorAppName=your_vendorAppName
 # vendorAppVersion=your_vendorAppVersion
 ```

### Set up your application

1. Add the CWS wrapper library to your application.
 - Add a reference to `CWSWrapper.dll` in the Solution Explorer.
 - Add a `using CWSWrapper;` statement to any files that use that DLL.

2. Create and initialize an instance of CWS.

 ```c#
 private string m_PaymentGatewayId;
 private CWS m_CWS;
 ....
 m_CWS = new CWS();
 m_CWS.Start("path to log file.txt", 4);
 ```

3. Open the payment gateway.

 
 :::::notice{note}

 Once you establish a link, you'll use use the `paymentGatewayIn` in any future calls to the gateway.
 
 :::::


 ```c#
 OpenPaymentArgs obea = new OpenPaymentArgs();
 obea.merchantId = MY_MERCHANT;
 obea.userId = MY_USER;
 obea.pin = MY_PIN;
 obea.app = MY_APP;
 obea.vendorId = MY_VENDOR_ID;
 obea.vendorAppName = MY_VENDOR_APP_NAME;
 obea.vendorAppVersion = MY_VENDOR_APP_VERSION;
 obea.partnerAppId = MY_PARTNER_APP_ID; // optional Converge partner app id
 obea.email = IGNORE_ME; // Ignore this parameter; we're removing it in a future release.
 obea.paymentGatewayEnvironment = MY_SERVERTYPE;
 obea.handleDigitalSignature = false;
 ```

 For RBA & UPP PIN pads only, you have the option to override the default language for Canadian transactions. If you do not specify a language, the transaction defaults to the server setting. Commerce SDK supports English and French in Canada.

 ```c#
 obea.overrideDefaultTerminalLanguage = new OverrideDefaultTerminalLanguage();
 obea.overrideDefaultTerminalLanguage.languageInformation = new LanguageInformation();
 obea.overrideDefaultTerminalLanguage.languageInformation.languageCode = ...;
 obea.overrideDefaultTerminalLanguage.languageInformation.countryCode = ...;
 ```

 For US RBA & UPP PIN pads only, you have the option to override the Commerce SDK the US debit network preference. If you do not specify a preference, Commerce SDK uses the server-supplied value. Valid Values: global debit network, us common debit network and no preference. No preference prompts the user to make the selection on PIN pad. Contactless transactions: PIN pad does not ask user for a selection. The PIN pad selects the AID with the highest priority remaining after applying setting filters. For example, if the setting is the global debit network and there are two global AIDs on the card, the PIN pad selects the AID with the highest priority.

 ```c#
 obea.overrideDebitNetworkPreferences = new OverrideDebitNetworkPreferences();
 obea.overrideDebitNetworkPreferences.visa = ...;
 obea.overrideDebitNetworkPreferences.mastercard = ...;
 obea.overrideDebitNetworkPreferences.discover = ...;

 OpenPaymentGatewayResults results = m_CWS.OpenPaymentGateway(obea, null);
 if (null != results.OpenPaymentData)
 {
 // Save the paymentGatewayId for future use
 m_PaymentGatewayId = results.OpenPaymentData.paymentGatewayId;
 }
 ```

4. Run a credit card Sale transaction.

 ```c#
 PaymentArgs pa = new PaymentArgs();
 pa.paymentGatewayId = m_PaymentGatewayId;
 Money m = new Money(Money.CurrencyCodefromString("USD"), myAmount);
 pa.baseTransactionAmount = m;
 pa.tenderType = TenderType.CARD;
 pa.transactionType = TransactionType.SALE;
 m_CWS.StartPaymentTransaction(pa, MyNotifyCWSEvent, MyPaymentComplete);
 ```

5. Handle event notifications.

 ```c#
 public void MyNotifyCWSEvent(CWSEvent cwsevent)
 {
 /* cwsevent.statusDetails will contain simple messages like
 CARD_READER_TRANSACTION_STARTED
 CARD_ENTRY_PROMPTED
 CARD_SWIPED
 ...
 */
 }
 ```

6. Receive transaction results.

 ```c#
 public void MyPaymentComplete(PaymentTransactionResults ptr)
 {
 m_ChanId = ptr.getChanId();
 PaymentTransactionData ptdata = ptr.PaymentTransactionData;
 if (null != ptdata)
 {
 // PaymentTransactionData contatins all the details of the transaction
 }
 }
 ```

## C# interface to the CWS REST API

The C# interface handles the REST API details to simplify what you interact with at the end of the transaction. Commerce SDK summarizes the results for each transaction in a `Results` object.

### Getting started

1. Create an instance of CWS.

 ```c#
 CWS m_CWS = new CWS();
 ```

2. Call its `Start` method.

 ```c#
 m_CWS.Start(“c:\\somedir\\mylog.log”, 4);
 ```

3. Pass the filename for logging debug information and a level 1 (least) to 4 (most). 

4. Call the `Stop` method before exiting your application.

 Now you're ready to call any method.

### Namespace

All CWS functions are defined in the **CWSWrapper** namespace. You can either precede all CWS references with CWSWrapper or add a `"using CWSWrapper;"` at the beginning of each of module.

### Returned results objects

All results objects normally contain one or more objects that contain properties of interest.

For example, the card read function returns the cardholder's first and last names. `CardReadResults` stores these data in a `CardData` object.

Assuming `crr` is a `CardReadResults` object, you can obtain the values:

```c#
CardData cd = crr.CardData;
String lastname = cd.lastName;
String firstname = cd.firstName;
…
```

### Properties of CWS

| Property | Description |
| --- | :--- |
| URL | String defaults to `https://localhost:9790/rest/command`. *Note:* If the URL changes, you need to set this property. |
| DelayMillis | Integer for the number of milliseconds to wait between REST API calls to check on status. Default value: 250 (1/4 second). |
| MaxWaitMillis | Integer for the maximum number of miilliseconds the interface will spend sending REST API status calls. Default value: 60,000 (60 seconds). *Note:** -1 means no time limit. |

### Notifications

This layer may produce informational messages you find useful.

#### Use case

The card reader usually faces the customer and the cashier cannot see what the reader display reads. Suppose a terminal prompt confuses the customer; if the cashier knew where the customer was in the transaction process, the cashier could quickly help navigate the prompt without the customer even having to ask.

You can pass a delegate listener to all functions to receive these notifications. Pass a delegate listener as a `CWSEvent`.

```c#
public class CWSEvent
{
 public String timeStamp { get; set; }
 public String statusDetails { get; set; }
}
```

The delegate looks like:

```c#
public void MyNotifyCWSEvent(CWSEvent cwsevent)
{
// Do something with the event
}
```

:::::notice{note}

You must call this delegate on a separate thread.
:::::


### Synchronous or asynchronous

All functions can run **synchronously** or **asynchronously**.

To run functions **asynchronously**, pass a `Start` method and a delegate to handle the completion.

Now you can call any method.
 
**A word about naming**

Let's take an example method,  `Foo`.

The name of the **synchronous** version is  `Foo` and the **asynchronous** version is  `StartFoo`.

The results are  `FooResults` and the delegate signature is  `FooComplete(FooResults)`.

#### Examples

You want to perform a sale transaction. This returns a `BackEndResults` object.

##### Calling synchronously

```c#
PaymentTransactionResults ptr = m_CWS.PaymentTransaction(bea, MyNotifyCWSEvent);
```

##### Calling asynchronously

```c#
public void MyPaymentComplete(PaymentTransactionResults ber)
{
// Do something with the results
}

…

// Returns right away; MyBackEndComplete called later
m_CWS.StartPaymentTransaction(bea, MyNotifyCWSEvent, MyPaymentComplete);
```

##### More information required

Commerce SDK uses callbacks to obtain additional information during a transaction.

Normally, your call to `BackEnd` does not return until finished with the transaction results available. However, if the SDK needs information, it returns before completion with a request for additional information.

You must check if `BackEndResults.getRequiredInformation` is null (`BackEndResults.BackEndTransactionData` will be null). These strings will tell you what information to supply.

Likewise, if you use `StartBackEnd`, `requiredInformation` calls your `BackEndComplete` method.

This is a `BackEndComplete` example:

```c#
public void MyPaymentComplete(PaymentTransactionResults ber)
{
 String chanId = ber.getChanId();
 PaymentTransactionData betd = ber.PaymentTransactionData;
 if (null != betd) // Results available?
 {
 m_TransData = betd;
 if ((null != betd.approved) && (betd.approved.Equals("yes")) 
 // Transaction approved?
 ...
 }
 else if (null = ber.getRequiredInformation())
 {
 // Determine what additional information is necessary
 }
```

You continue the transaction once you obtain the additional required information. For example, if `VoiceReferral` is required, you could continue the transaction like this:

```c#
Dictionary<string, string> info = new Dictionary<string, string>();
info["VoiceReferral"] = theVoiceReferral;
m_CWS.StartContinuePaymentTransaction(m_PaymentGatewayId, chanId, info, MyNotifyCWSEvent, MyPaymentComplete);
```

Alliance Offers

Data as a Service

Invitation to Apply

Accounts

Bank Holidays

Card Activation

Card Controls

Challenge-Widget

Commercial Credit Cards

Commercial Statements

Credit Card Account Details

Credit Card Accounts Overview

Credit Card Alerts

Credit Card Application Status

Credit Card APRs

Credit Card Balance Transfers

Credit Card Disputes

Credit Card Payments

Credit Card Qualified Offers

Credit Card Statements

Credit Card Transactions

Data Sharing for Marketing Purposes

Digital Wallets

Make a Payment - Coming Soon

Rewards Accelerator

Rewards Automatic Redemption

Rewards: Balance Summary

Rewards: Dashboard

Rewards Redemption Accounts

Rewards Redemptions

Rewards Transactions: Earned and Redeemed

Travel Notifications

User Profile

3DSecure2

Avvance

CheckoutJs

Commerce SDK

Converge

Disputes Management

Dynamic Currency Conversion

eBoarding

Elavon Cloud Payments Interface

Elavon Payment Gateway

Fusebox

Hosted Payment Page

In Person Payments on Opayo

Leads

Lightbox payment modal

Online Payments on Opayo

Opayo

Opayo Direct

Opayo Forms

Opayo Reporting API

Opayo Server

Opayo Shared API

Payment Method Gateway

Payments Core 365

Simplify

viaconex

XML API

Card as a Service API

Core Banking API

Money Movement API

Reference API

Access Online Transactions

Account Transfers

Account Validation

ACH Originations

Bank Information

Card as a Service

Check Payables

Corporate Account Information

Corporate Account Information 3LO

Corporate Credit Cards

Corporate Onboarding

Corporate Statements

Custody

Data Toolbox

Data Toolbox - Accounts

Data Toolbox - Documents

Data Toolbox - Transactions

Debit Card Phone Number Lookup

Disbursements via Zelle®

U.S. Bank Flexible Capital Platform

Freight Payment Customer Profiles

Freight Payment Transactions

Incoming Webhooks

Instant Payments

Investment Accounting

PaySmart

Payee Choice

Payee Token+

Personal Loans

Positive Pay

Push to Card

Receivables

RTP® - Real-Time Payments

Tokenized Payments

Treasury Builder

U.S. Bank FBO Account

Virtual Account Reporting

Virtual Card Payments

Voyager Accounts

Voyager Cards

Voyager Drivers

Voyager Transactions

Voyager Vehicles

Wire Transfers

Elavon Commerce SDK Overview

Integration Methods

Commerce Web Services

Java (Windows)

Java (Android)

Objective-C (iOS)

System

Get Environment Information

Get Converge Account Information

Validate BMS Credentials

Payment Terminals

Payment Terminals Overview

Ingenico

iCMP

iPP320

iSC250

Lane/3000

Lane/3600

Lane/5000

Link/2500

Moby/5500

RP457c

Self/4000

Card Reader Connection

Device Connection Criteria

Card Reader Configuration

Get Card Reader Information

24-Hour Reboot

On-Demand

Get Device Status

Reset Card Reader

Reboot Card Reader

Encrypted Card Read

Cancel Card Read

Prompt PIN Entry

Capture Card Data

Get Customer Input

Phone Number

Volume Control

Set Shutdown Timeout

Signature Capture

Set Time Zone on Card Reader

TMS Update Check Time Window

SSL Certificate Update Process for Card Reader

Printers

Printers Overview

Get Printer Information

Print Receipts

On Demand Print Receipt

Transaction Types

Transactions Overview

Sale

Auth Only

Auth Only Increment

Convert Auth Only to Sale

Auth Only Reversal

Void

Linked Refund

Stand Alone Refund

Debit Balance Inquiry

Post Auth Tip Adjust

Continue Transaction

Cancel Transaction

Transaction Lookup

Processing Options

Processing Options Overview

Address Verification Service

Force Sale

Gratuity

Manual Card Data Entry

Merchant Transaction Reference

Partial Approval

Token Request

Pay with Token

Retrieve CVM Signature

Invoice Number

Lane Number