Complete API Spec

Overview

EdgeExpress encapsulates all of the logic for EMV transactions and formats required receipt elements removing the need for point of purchase applications to certify for EMV transaction processing. EdgeExpress also allows point of purchase applications to control the configured PIN Pad device for other functions based on device support, such as signature capture and customer prompts. Multiple devices are supported by EdgeExpress, and the point of purchase application is isolated from the complexities of communicating with the configured device.

Supported Operation Systems

The following Windows operating systems are supported with EdgeExpress.

• Windows 7
• Windows 8
• Windows 8.1
• Windows 10
• Windows Server 2008
• Windows Server 2012
• Windows Server 2016

Microsoft .NET framework 4.5 or higher is required to use EdgeExpress.

EdgeExpress offers two ways of connecting to the API. EdgeExpress PC offers a .NET DLL with a COM Object which supports locally installed Windows Applications including Microsoft Terminal Services Environments, and EdgeExpress Cloud which supports an HTTP GET method and supports both locally installed and Web Applications. Both of these methods are explained further below.

EdgeExpress PC supports a single function interface with an input and output string parameter. EdgeExpress PC requests are formatted as XML format. The output is returned as XML. The Execute() method is used for this format.

XML Format

A simple XML format is used for XML request strings. Only one transaction request is allowed in each XML request string. All fields must provide a value.
Example:
    <REQUEST>        <Field1\>Value</Field1\>        <Field2\>Value</Field2\>    </REQUEST>

.Net Integration

EdgeExpress PC is a .Net library and supports direct .Net integration to the EdgeExpress PC library. A single interface is provided that accepts the transaction and function requests in XML format. Results are returned as XML.

• Namespace: XCharge.XpressLink2
• Object: XLEmv
• Method: Void Execute(string requestParameters, out string responseXML);
  Please refer to the EdgeExpress PC sample applications provided in the EdgeExpress PC SDK for code examples related to integrating to the .Net library.

COM Integration

EdgeExpress PC also exposes a legacy COM interface, allowing integration to EdgeExpress PC using non-.Net development environments. A single interface is provided that accepts the transaction and function requests in XML format.

• COM Object: XCharge.XpressLink2.XLEmv
• Method: Execute(BSTR parameterString/\*\[in\]\*/, BSTR\* response/\*\[out\]\*/);

EdgeExpress PC Request Process

1. Point of Purchase application calls the blocking Execute() method with the request string in the requestParameters parameter.

2. EdgeExpress PC communicates with the device and processes the transaction request.

3. EdgeExpress PC returns the result of the request in the responseXML parameter.

4. Point of Purchase application parses the request response and takes appropriate actions.

EdgeExpress Cloud uses request data which contains the parameters for the transaction you are sending to the RCM URL. Use an HTTP GET request to receive a response. When creating the GET request, add the content type (application/xml, or application/json) to the request header you would like to use for the response. If you do not add a content type, it will default to a JSON format response. If your response is in JSON format, look under the RCMRESPONSE tag for response data. If your response is in XML format, look under the XMLRCMRESPONSE tag for response data.

RCM URL Example:

https://localsystem.paygateway.com:21113/RcmService.svc/Initialize?callback=jsonpResponse&xl2Parameters=<REQUEST><Field1>Value1</Field1><Field2>Value2</Field2></REQUEST>

EdgeExpress Cloud Request Process

1. Point of Purchase application calls the RCM URL passing in the request string in the xl2Parameters parameter.

2. EdgeExpress Cloud communicates with the device and processes the request.

3. EdgeExpress Cloud returns the results of the request.

4. Point of Purchase application parses the request response and takes appropriate actions.

Listed below are the request fields REQUIRED for processing a transaction through the EdgeExpress API.

The following section breaks down the different Credit Card Transaction requests and responses.

Transaction Type used to purchase goods and services in a Card Not Present environment. The Integrator will be provided a "Session Token", which will be used for generation of the Hosted Payment Page.

Credit Sale - Request

<REQUEST>
  <XWEBID>800000012368</XWEBID>
  <XWEBTERMINALID>80026461</XWEBTERMINALID>
  <XWEBAUTHKEY>Ys08rfdjcVYCJV2XDkoxzcftK9PgpMLH</XWEBAUTHKEY>
  <TRANSACTIONTYPE>CREDITSALE</TRANSACTIONTYPE>
  <AMOUNT>1.00</AMOUNT>
  <ADDRESS>123 Fake Street</ADDRESS>
  <ALLOWDUPLICATES />
  <CLERK>Clerk</CLERK>
  <INVOICENO>INV001</INVOICENO>
  <ORDERID>123</ORDERID>
  <RECEIPTADDRESS>456 Merchant Street</RECEIPTADDRESS>
  <RECEIPTCOPYLABEL>MERCHANT_COPY</RECEIPTCOPYLABEL>
  <ZIP>12345</ZIP>
</REQUEST>

Credit Sale - Response

<RESPONSE>
	<DUPLICATECARD>True</DUPLICATECARD>
	<DATE_TIME>09-05-19 13:24:10</DATE_TIME>
	<HOSTRESPONSECODE>000</HOSTRESPONSECODE>
	<HOSTRESPONSEDESCRIPTION>Approval</HOSTRESPONSEDESCRIPTION>
	<RESULT>0</RESULT>
	<RESULTMSG>Success</RESULTMSG>
	<APPROVEDAMOUNT>1.00</APPROVEDAMOUNT>
	<BATCHNO>000116</BATCHNO>
	<BATCHAMOUNT>5622.04</BATCHAMOUNT>
	<APPROVALCODE>000163</APPROVALCODE>
	<ACCOUNT>476173XXXXXX0010</ACCOUNT>
	<AVSRESPONSECODE>R</AVSRESPONSECODE>
	<CARDHOLDERNAME>Test/Card 01              </CARDHOLDERNAME>
	<CARDTYPE>Credit</CARDTYPE>
	<CARDBRAND>VISA</CARDBRAND>
	<CARDBRANDSHORT>VS</CARDBRANDSHORT>
	<LANGUAGE>ENGLISH</LANGUAGE>
	<ALIAS>cju0ocf1KR</ALIAS>
	<ENTRYTYPE>Chip</ENTRYTYPE>
	<RECEIPTTEXT>          456 Merchant Street

Terminal ID         XXXXXXXXXXXX381
Trans ID            000000001720
Order ID            123
Receipt #           INV001
Payment Type        Credit
Trans Type          Purchase
Clerk ID            Clerk
Date/Time           2019-09-05 13:24:10
Card Type           Visa
Card Number         XXXXXXXXXXXX0010
Entry Legend        CHIP READ
Entry Method        CONTACT
Approval Code       000163
AC                  7F30732194D711B8
ATC                 001B
AID                 A0000000031010
AID NAME            Visa Credit
TVR                 0280008000
TSI                 E800
Resp CD             00
TRN REF #           309248626500291
VAL CODE            LJCK

Total Amount        USD$1.00

Description:_______________________

          Approved - Thank You

 X____________________________________
          Cardholder Signature

Buyer agrees to pay total amount above
according to cardholder's agreement with
issuer.

         ****Merchant Copy****</RECEIPTTEXT>
	<EXPMONTH>12</EXPMONTH>
	<EXPYEAR>22</EXPYEAR>
	<TRANSACTIONID>000000001720</TRANSACTIONID>
	<ORDERID>123</ORDERID>
	<EMVTRANSACTION>True</EMVTRANSACTION>
</RESPONSE>

This transaction removes a Sale, Capture or Return transaction from the current batch. It can also be used to reverse the Authorization or Sale transaction; thereby, replenishing the authorized amount on the consumer card.

Credit Void - Request

<REQUEST>
  <XWEBID>800000012368</XWEBID>
  <XWEBTERMINALID>80026461</XWEBTERMINALID>
  <XWEBAUTHKEY>Ys08rfdjcVYCJV2XDkoxzcftK9PgpMLH</XWEBAUTHKEY>
  <TRANSACTIONTYPE>CREDITVOID</TRANSACTIONTYPE>
  <RECEIPTADDRESS>456 Merchant Street</RECEIPTADDRESS>
  <RECEIPTCOPYLABEL>MERCHANT_COPY</RECEIPTCOPYLABEL>
  <REFERENCEORDERID>OrderID of the Transaction you wish to Void</REFERENCEORDERID>
</REQUEST>

Return is processed using an "ORDERID" from a previous transaction; this method is recommended for use wherever possible. When performing a Dependent Return, the payment page is not required; the Edge Gateway will use the card details of the previous transaction being referenced.

Credit Dependent Return - Request

<REQUEST>
  <XWEBID>800000012368</XWEBID>
  <XWEBTERMINALID>80026461</XWEBTERMINALID>
  <XWEBAUTHKEY>Ys08rfdjcVYCJV2XDkoxzcftK9PgpMLH</XWEBAUTHKEY>
  <TRANSACTIONTYPE>CREDITRETURN</TRANSACTIONTYPE>
  <AMOUNT>1.00</AMOUNT>
  <CLERK>Clerk</CLERK>
  <INVOICENO>INV001</INVOICENO>
  <RECEIPTADDRESS>456 Merchant Street</RECEIPTADDRESS>
  <RECEIPTCOPYLABEL>MERCHANT_COPY</RECEIPTCOPYLABEL>
  <REFERENCEORDERID>OrderID of Transaction you wish to Return</REFERENCEORDERID>
</REQUEST>

Return is processed without reference to a previous transaction; this method requires use of a payment page for manual entry of the customer's credit card details.

Credit Independent Return - Request

<REQUEST>
  <XWEBID>800000012368</XWEBID>
  <XWEBTERMINALID>80026461</XWEBTERMINALID>
  <XWEBAUTHKEY>Ys08rfdjcVYCJV2XDkoxzcftK9PgpMLH</XWEBAUTHKEY>
  <TRANSACTIONTYPE>CREDITRETURN</TRANSACTIONTYPE>
  <AMOUNT>21.00</AMOUNT>
  <CLERK>Clerk</CLERK>
  <INVOICENO>INV001</INVOICENO>
  <RECEIPTADDRESS>456 Merchant Street</RECEIPTADDRESS>
  <RECEIPTCOPYLABEL>MERCHANT_COPY</RECEIPTCOPYLABEL>
</REQUEST>

This transaction will verify the available funds on the card. The funds will be reserved on the cardholders account for a period of time. The subsequent CREDITCAPTURE on this transaction will flag the transaction for settlement.

Credit Authorization - Request

<REQUEST>
  <XWEBID>800000012368</XWEBID>
  <XWEBTERMINALID>80026461</XWEBTERMINALID>
  <XWEBAUTHKEY>Ys08rfdjcVYCJV2XDkoxzcftK9PgpMLH</XWEBAUTHKEY>
  <TRANSACTIONTYPE>CREDITAUTH</TRANSACTIONTYPE>
  <AMOUNT>1.00</AMOUNT>
  <ADDRESS>123 Fake Street</ADDRESS>
  <CLERK>Clerk</CLERK>
  <INVOICENO>INV001</INVOICENO>
  <ORDERID>12345</ORDERID>
  <RECEIPTADDRESS>456 Merchant Street</RECEIPTADDRESS>
  <RECEIPTCOPYLABEL>MERCHANT_COPY</RECEIPTCOPYLABEL>
  <ZIP>12345</ZIP>
</REQUEST>

This transaction is a request to post a previously authorized transaction. An online capture is a transaction that flags an authorization previously approved via the EdgeExpress Gateway for settlement.

Credit Capture - Request

<REQUEST>
  <XWEBID>800000012368</XWEBID>
  <XWEBTERMINALID>80026461</XWEBTERMINALID>
  <XWEBAUTHKEY>Ys08rfdjcVYCJV2XDkoxzcftK9PgpMLH</XWEBAUTHKEY>
  <TRANSACTIONTYPE>CREDITONLINECAPTURE</TRANSACTIONTYPE>
  <AMOUNT>5.00</AMOUNT>
  <ADDRESS>123 Fake Street</ADDRESS>
  <CLERK>Clerk</CLERK>
  <INVOICENO>INV001</INVOICENO>
  <RECEIPTADDRESS>456 Merchant Street</RECEIPTADDRESS>
  <RECEIPTCOPYLABEL>MERCHANT_COPY</RECEIPTCOPYLABEL>
  <REFERENCEORDERID>OrderID of the Auth that you want to Capture</REFERENCEORDERID>
  <ZIP>12345</ZIP>
</REQUEST>

The following section breaks down the different Debit Card Transaction requests.

This transaction is used to complete a debit card purchase transaction. A debit PIN Pad is required to get the PIN and Key block required by the transaction. The debit card track 2 information is also required to complete a debit sale transaction.

Debit Sale - Request

<REQUEST>
  <XWEBID>800000012368</XWEBID>
  <XWEBTERMINALID>80026461</XWEBTERMINALID>
  <XWEBAUTHKEY>Ys08rfdjcVYCJV2XDkoxzcftK9PgpMLH</XWEBAUTHKEY>
  <TRANSACTIONTYPE>DEBITSALE</TRANSACTIONTYPE>
  <AMOUNT>35.00</AMOUNT>
  <ADDRESS>123 Fake Street</ADDRESS>
  <ALLOWDUPLICATES />
  <CLERK>Clerk</CLERK>
  <INVOICENO>INV001</INVOICENO>
  <ORDERID>12345678</ORDERID>
  <RECEIPTADDRESS>456 Merchant Street</RECEIPTADDRESS>
  <RECEIPTCOPYLABEL>MERCHANT_COPY</RECEIPTCOPYLABEL>
  <ZIP>12345</ZIP>
</REQUEST>

This transaction is used to return funds to a debit card. A debit PIN Pad is required to get the PIN and Key block required by the transaction. The debit card track 2 information is also required to complete a debit return transaction. Debit Return is disabledby default on the merchant account but can be enabled upon request.

Debit Return - Request

<REQUEST>
  <XWEBID>800000012368</XWEBID>
  <XWEBTERMINALID>80026461</XWEBTERMINALID>
  <XWEBAUTHKEY>Ys08rfdjcVYCJV2XDkoxzcftK9PgpMLH</XWEBAUTHKEY>
  <TRANSACTIONTYPE>DEBITRETURN</TRANSACTIONTYPE>
  <AMOUNT>35.00</AMOUNT>
  <CLERK>Clerk</CLERK>
  <INVOICENO>INV001</INVOICENO>
  <ORDERID>New OrderID, Debit Return must be independent. No reference OrderID here.</ORDERID>
  <RECEIPTADDRESS>456 Merchant Street</RECEIPTADDRESS>
  <RECEIPTCOPYLABEL>MERCHANT_COPY</RECEIPTCOPYLABEL>
</REQUEST>

Sale - Request (Allows User to Select Debit/Credit On Device)

<REQUEST>
  <XWEBID>800000012368</XWEBID>
  <XWEBTERMINALID>80026461</XWEBTERMINALID>
  <XWEBAUTHKEY>Ys08rfdjcVYCJV2XDkoxzcftK9PgpMLH</XWEBAUTHKEY>
  <TRANSACTIONTYPE>SALE</TRANSACTIONTYPE>
  <AMOUNT>1.00</AMOUNT>
  <ADDRESS>123 Fake Street</ADDRESS>
  <ALLOWDUPLICATES />
  <CLERK>Clerk</CLERK>
  <INVOICENO>INV001</INVOICENO>
  <ORDERID>12345678910</ORDERID>
  <RECEIPTADDRESS>456 Merchant Street</RECEIPTADDRESS>
  <RECEIPTCOPYLABEL>MERCHANT_COPY</RECEIPTCOPYLABEL>
  <ZIP>12345</ZIP>
</REQUEST>

The following section breaks down the various PIN Pad Device transaction types.

Prompts for a signature. A device that supports signature capture must be configured as the current PIN Pad device.

Signature Prompt - Request

<REQUEST>
  <TRANSACTIONTYPE>PPDPROMPTSIGNATURE</TRANSACTIONTYPE>
  <DISPLAYCAPTUREDSIGNATURE>T</DISPLAYCAPTUREDSIGNATURE>
  <TITLE>Please Sign</TITLE>
  <SIGNATUREFILEFORMAT>BMP</SIGNATUREFILEFORMAT>
</REQUEST>

Signature Prompt - Response

<RESPONSE>
	<SIGNATUREFILENAME>C:\Users\Admin\AppData\Local\Temp\Signature_00.bmp</SIGNATUREFILENAME>
	<SIGNATUREFORMAT>BMP</SIGNATUREFORMAT>
	<RESULT>0</RESULT>
</RESPONSE>

Prompts the user to select Yes or No. If the PIN Pad device supports a Yes/No prompt then the device prompts in addition to a dialog that prompts for Yes or No. Either the device or dialog can be selected. If the device does not support the prompt then only a dialog prompt displays.

Prompt Yes/No - Request

<REQUEST>
  <TRANSACTIONTYPE>PPDPROMPTYESNO</TRANSACTIONTYPE>
  <TITLE>Yes or No?</TITLE>
  <TEXT>ASDF</TEXT>
</REQUEST>

Prompt Yes/No - Response

<RESPONSE>
	<YESORNO>Y</YESORNO>
	<RESULT>0</RESULT>
</RESPONSE>

Displays formatted text on the signature capture device. Text can be formatted using the HTML equivalent formatting codes documented below. Only these formatting codes are supported. The number of lines and characters on each line is dependent on the device capabilities. Color codes sent to a device that cannot display colors are stripped out of the text. Text lines aredisplayed starting with the first line until the screen is full. The text is not scrolled to display additional lines.After using PPDDISPLAYTEXT, submit PPDCLOSE transaction request before initiating direct RBAintegration with device.

Display Text - Request

<REQUEST>
  <TRANSACTIONTYPE>PPDDISPLAYTEXT</TRANSACTIONTYPE>
  <TEXT>Welcome</TEXT>
</REQUEST>

Display Text - Response

<RESPONSE>
	<RESULT>0</RESULT>
</RESPONSE>

GETRCMCURRENTUSERPORT is sent through EdgeExpress PC to gather the User Port of the current user.

Get RCM Port (Used for Terminal Services, EdgeExpress PC Only) - Request

<REQUEST>
  <TRANSACTIONTYPE>GETRCMCURRENTUSERPORT</TRANSACTIONTYPE>
</REQUEST>

Get RCM Port (Used for Terminal Services, EdgeExpress PC Only) - Response

<RESPONSE>
	<RCMPORT>21113</RCMPORT>
	<RESULT>0</RESULT>
	<RESULTMSG>Success</RESULTMSG>
</RESPONSE>