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

PropertyDescription
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

PropertyDescription
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

PropertyDescription
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

PropertyDescription
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

PropertyDescription
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

PropertyDescription
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
  }
}