Transactions
These are the payment transactions that you can integrate into your application:
In this topic:
Prerequisite
Send Converge Credentials
Before you can post any transaction requests, you need to send your Converge credentials to Commerce SDK using the openPaymentGateway
command to initialize your application. After Commerce SDK receives your credentials, it uses these for all subsequent communications with Converge.
important
- You should execute
openPaymentGateway
only once. - The
paymentGatewayId
parameter and value in the response must be passed to all subsequent transaction requests.
Request
Property | Description |
---|---|
method string | required | openPaymentGateway |
targetType string | required | paymentGatewayConverge |
parameters JSONObject | required | All relevant parameters for opening a connection. |
vendorId string | required | Vendor ID Unique vendor idenitifier provided by Elavon. |
vendorAppName string | required | Vendor’s Application Name |
vendorAppVersion string | required | Application Version |
userId string | required | User ID |
pin string | required | PIN |
paymentGatewayEnvironment string | required | Payment Gateway Environment Valid values: - PROD - DEMO |
app string | required | Application Name |
merchantId string | required | Merchant ID |
handleDigitalSignature boolean | required | Digital Signature Capture Capability Valid values: - True - False |
email string | optional | Merchant’s Email Address |
overrideDefaultTerminalLanguage JSONObject | optional | Language and Country Information Note: For RBA connector PIN pads only. |
overrideDebitNetworkPreferences JSONObject | optional | US Common Debit Preferences |
Response
Property | Description |
---|---|
paymentGatewayId boolean | Payment Gateway ID Unique payment gateway identifier to be used on all subsequent requests. |
result boolean | Transaction Result |
Code Samples
CWS
Request
{
"method" : "openPaymentGateway",
"requestId" : "1326383996",
"targetType" : "paymentGatewayConverge",
"version" : "1.0",
"parameters" : {
"app" : "VMM",
"email" : "******",
"pin" : "******",
"userId" : "******",
"handleDigitalSignature" : true,
"paymentGatewayEnvironment" : "DEMO",
"vendorId" : "******",
"vendorAppName" : "******",
"vendorAppVersion" : "******",
"overrideDefaultTerminalLanguage" : {
"languageInformation" : {
"languageCode" : "UNSET",
"countryCode" : "UNSET"
}
},
"overrideDebitNetworkPreferences" : {
"visa" : "NO_PREFERENCE",
"mastercard" : "US_COMMON_DEBIT",
"discover" : "GLOBAL_NETWORK"
}
}
}
Response
{
"requestId" : "1326383996",
"statusDetails" : "REQUEST_ACCEPTED",
"data" : {
"paymentGatewayCommand" : {
"completed" : true,
"eventQueue" : [ ],
"openPaymentGatewayData" : {
"result" : "SUCCESS",
"paymentGatewayId" : "0907356b-d985-4e3f-adae-1a74b9264a8a"
}
}
}
}
C#
OpenPaymentArgs opa = new OpenPaymentArgs();
opa.merchantId = MY_MERCHANT;
opa.userId = MY_USER;
opa.pin = MY_PIN;
opa.app = MY_APP;
opa.email = MY_EMAIL;
opa.vendorId = MY_VENDOR_ID;
opa.vendorAppName = MY_VENDOR_APP_NAME;
opa.vendorAppVersion = MY_VENDOR_APP_VERSION;
opa.paymentGatewayEnvironment = MY_SERVERTYPE;
opa.handleDigitalSignature = true; /* We can handle digital signature */
// The language used for transaction can be overridden.
// This applies to RBA pinpads only and will have no effect for other pinpads.
// This is completely optional. If not used, a possibly server supplied language preference info is going to be used.
// You can specify a pair of (language, country) to determine the language to be used on pinpad during a transaction.
// If the pair you supplied is not supported, the return value will indicate the language CSDK chose to use.
// This is determined to be the closest match to what you specified.
// Currently, CSDK supports English in US and English and French in Canada.
opa.overrideDefaultTerminalLanguage = new OverrideDefaultTerminalLanguage();
opa.overrideDefaultTerminalLanguage.languageInformation = new LanguageInformation();
opa.overrideDefaultTerminalLanguage.languageInformation.languageCode = MY_OVERRIDE_LANGUAGE_LANGUAGE_CODE;
opa.overrideDefaultTerminalLanguage.languageInformation.countryCode = MY_OVERRIDE_LANGUAGE_COUNTRY_CODE;
// You can override the CSDK setting for the debit network preference in the US.
// This applies to US RBA pinpads only and will have no effect for other pinpads.
// This is completely optional. If not used, a possibly server supplied value is going to be used.
// The possible choices are: global debit network, us common debit network or no preference at all,
// in which case the user will be asked to do the selection on the pinpad, if applicable.
// Be advised that in case of contactless transactions, the pinpad will not ask the user for a selection,
// but it will select the AID with the highest priority remaining after filtering them based on the setting.
// For example, if the choice is to use the global network and there 2 global AIDS on the card,
// RBA will automatically select the one with the highest priority.
opa.overrideDebitNetworkPreferences = new OverrideDebitNetworkPreferences();
opa.overrideDebitNetworkPreferences.visa = MY_VISA_PREF;
opa.overrideDebitNetworkPreferences.mastercard = MY_MASTERCARD_PREF;
opa.overrideDebitNetworkPreferences.discover = MY_DISCOVER_PREF;
OpenPaymentGatewayResults opgr = m_CWS.OpenPaymentGateway(opa, null);
MyOpenPaymentGatewayComplete(opgr);
...
public void MyOpenPaymentGatewayComplete(OpenPaymentGatewayResults opgr)
{
OpenPaymentData opd = opgr.OpenPaymentData;
if (null != opd)
{
// success, store the payment gateway id
}
else
{
// failure
}
}
RBA PINPad Processing Options
RBA PINPad Language
This method overrides the language used on an RBA pinpad during a transaction.
Request
Property | Description |
---|---|
method string | required | overrideDefaultTerminalLanguage |
requestId string | required | Transaction Request ID |
targetType string | required | api |
parameters JSONObject | required | All relevant parameters for overriding the language on an RBA pinpad. |
languageInformation JSONObject | required | Holds the language information |
languageCode string | optional | ISO Language Code Valid values: - EN - FR |
countryCode string | optional | ISO Country Code Valid values: - US - CA |
Response
Property | Description |
---|---|
requestId string | Transaction request ID specified in request. |
statusDetails string | Status of the request. |
data JSONObject | Object holding various responses. |
countryCode string | Holds the ISO country code that was set. This may differ from the code specified in the request if an unsupported value. |
languageCode string | Holds the ISO lanugage code that was set. This may differ from the code specified in the request if an unsupported value. |
completed boolean | Completion status of the request. |
Example Request
{
"method" : "overrideDefaultTerminalLanguage",
"requestId" : "386097750",
"targetType" : "api",
"version" : "1.0",
"parameters" : {
"languageInformation" : {
"languageCode" : "EN",
"countryCode" : "US"
}
}
}
Response
{
"requestId" : "386097750",
"statusDetails" : "REQUEST_ACCEPTED",
"data" : {
"countryCode" : "US",
"completed" : true,
"languageCode" : "EN"
}
}
US Debit Network Preference
This method overrides the US debit network preference used on an RBA pinpad during a transaction.
note
In case of contactless transactions, the pinpad will not ask the user for a selection but it will select the AID with the highest priority remaining after filtering these based on the setting.
Request
Property | Description |
---|---|
method string | required | overrideDebitNetworkPreferences |
requestId string | required | Transaction Request ID |
targetType string | required | api |
parameters JSONObject | required | All relevant parameters for overriding the US debit network preference on an RBA pinpad. |
discover string | optional | Preference for the Discover brand Valid values: - GLOBAL_NETWORK - US_COMMON_DEBIT - NO_PREFERENCE |
mastercard string | optional | Preference for the MasterCard brand Valid values: - GLOBAL_NETWORK - US_COMMON_DEBIT - NO_PREFERENCE |
visa string | optional | Preference for the Visa brand Valid values: - GLOBAL_NETWORK - US_COMMON_DEBIT - NO_PREFERENCE |
Response
Property | Description |
---|---|
requestId string | Transaction request ID specified in request. |
statusDetails string | Status of the request. |
data JSONObject | Object holding various responses. |
completed boolean | Completion status of the request. |
Example Request
{
"method" : "overrideDebitNetworkPreferences",
"requestId" : "386097749",
"targetType" : "api",
"version" : "1.0",
"parameters" : {
"discover" : "GLOBAL_NETWORK",
"mastercard" : "US_COMMON_DEBIT",
"visa" : "NO_PREFERENCE"
}
}
Response
{
"requestId" : "386097749",
"statusDetails" : "REQUEST_ACCEPTED",
"data" : {
"completed" : true
}
}