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.

error_outline
important
  • You should execute openPaymentGateway only once.
  • The paymentGatewayId parameter and value in the response must be passed to all subsequent transaction requests.

Request

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

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

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

      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.

      error_outline
      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

      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

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