C#

In this topic:

Prerequisites

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

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.

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)

error_outline
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

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.

    error_outline
    note

    You may need to remove and re-add the CWSWrapper and Newtonsoft.Json DLL filess 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.

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

    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.

    error_outline
    note

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

    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.email = IGNORE_ME; // Ignore this parameter; we're removing it in a future release.
    obea.paymentGatewayEnvironment = MY_SERVERTYPE;
    obea.handleDigitalSignature = false;

    For RBA 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.

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

    For US RBA 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. RBA 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, RBA selects the AID with the highest priority.

    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.

    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.

    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.

    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.

    CWS m_CWS = new CWS();
  2. Call its Start method.

    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:

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

Properties of CWS

URL String defaults to https://localhost:9790/rest/command.
error_outline
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).
error_outline
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.

public class CWSEvent
{
    public String timeStamp { get; set; }
    public String statusDetails { get; set; }
}

The delegate looks like:

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

error_outline
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
PaymentTransactionResults ptr = m_CWS.PaymentTransaction(bea, MyNotifyCWSEvent);
Calling Asynchronously
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:

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:

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