C#
In this topic:
Prerequisites
Before you get started, make sure to install the following:
- Visual Studio 2013 or later
- .NET Framework 4.5.2 or later
- Commerce Web Services
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). |
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
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
In Visual Studio, go to File/Open/Project/Solution and choose
SalesApp.sln
orTransApp.sln
.You are set to start building and debugging the sample application.
info_outlinenote
You may need to remove and re-add the
CWSWrapper
DLL files in your project’s References section.
Converge Credentials
Open the
CWSTransApp.properties
file in theCWSApp\CWSTransApp
directory.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
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.
- Add a reference to
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);
Open the payment gateway.
info_outlinenote
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.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.
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.
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; }
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);
Handle event notifications.
public void MyNotifyCWSEvent(CWSEvent cwsevent) { /* cwsevent.statusDetails will contain simple messages like CARD_READER_TRANSACTION_STARTED CARD_ENTRY_PROMPTED CARD_SWIPED ... */ }
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
Create an instance of CWS.
CWS m_CWS = new CWS();
Call its
Start
method.m_CWS.Start(“c:\\somedir\\mylog.log”, 4);
Pass the filename for logging debug information and a level 1 (least) to 4 (most).
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
Property | Description |
---|---|
URL | String defaults to https://localhost:9790/rest/command . info_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). info_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
}
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);