Transaction Processing API Reference Guide

1 Introduction

The Transaction Processing API is a web service that allows third-party applications to process transactions through E-xact's system.  The range of processing scenarios (Purchase, Refund, Pre-Authorization, etc.) enable flexible and powerful ways to implement custom business logic.  E-xact also provides free client libraries that ease integration with the API. 

The API is available in both SOAP and REST, where the latter supports XML and JSON message formats.  The same range of transaction processing scenarios is supported regardless of which style API you choose.

1.1 Basic Information

The service URLs are:

  • Endpoint - https://api.e-xact.com/transaction
  • WSDL - https://api.e-xact.com/transaction/wsdl

IMPORTANT NOTE: If you are using our DEMO site at rpm.demo.e-xact.com with a Gateway ID of "AD...", you will need to use the Endpoint : https://api.demo.e-xact.com/transaction.

Please refer to Appendix 1 for more information about legacy URLs.

Two pieces of information must be provided when you submit a transaction via the API, they are:

  • Exact ID - also known as the Gateway ID, this value identifies the Merchant and Terminal under which the transaction is to be processed
  • Password - authenticates the API request, this value should not be exposed to the public

These credentials can be submitted in two ways:

  • as HTTP Basic Authentication user name and password values
  • as part of the API message via the ExactID and Password properties

Examples in the next section will use these methods alternately, the choice of method is up to you.

1.2 A Few Examples Using cURL

The following examples submit transactions using the minimal required properties for each processing scenario.

NOTE: Exact ID and Password in the request and response have been substituted with the placeholders "ExactID" and "Password".

1.2.1 Example 1. Pre-Authorization

This request illustrates the following:

  • using the SOAP style API
  • passing authentication credentials as HTTP Basic Authentication username:password values
  • pre-authorizing the given credit card, which allows for capturing funds at a later time via the Completion transaction
curl -u 'ExactID:Password' \
     -H 'SOAPAction: http://secure2.e-xact.com/vplug-in/transaction/rpc-enc/SendAndCommit' \
     -H 'Content-Type: text/xml' \
     -d '<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/" xmlns:tns="http://secure2.e-xact.com/vplug-in/transaction/rpc-enc/" xmlns:types="http://secure2.e-xact.com/vplug-in/transaction/rpc-enc/encodedTypes" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<soap:Body soap:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<q1:SendAndCommit xmlns:q1="http://secure2.e-xact.com/vplug-in/transaction/rpc-enc/Request">
<SendAndCommitSource href="#id1" />
</q1:SendAndCommit>
<types:Transaction id="id1" xsi:type="types:Transaction">
<Transaction_Type xsi:type="xsd:string">01</Transaction_Type>
<DollarAmount xsi:type="xsd:string">15.75</DollarAmount>
<Card_Number xsi:type="xsd:string">4111111111111111</Card_Number>
<Expiry_Date xsi:type="xsd:string">1012</Expiry_Date>
<CardHoldersName xsi:type="xsd:string">Donald Duck</CardHoldersName>
</types:Transaction>
</soap:Body>
</soap:Envelope>' \
https://api.e-xact.com/transaction

The resulting request headers and response:

POST /transaction HTTP/1.1
Authorization: Basic Foo4BarBazAyOjAhcGl0ZXN0
User-Agent: curl/7.21.0 (i386-apple-darwin9.8.0) libcurl/7.21.0 OpenSSL/1.0.0a zlib/1.2.5 libidn/1.19
Host: api.e-xact.com
Accept: */*
SOAPAction: http://secure2.e-xact.com/vplug-in/transaction/rpc-enc/SendAndCommit
Content-Type: text/xml
Content-Length: 1057
Expect: 100-continue

HTTP/1.1 100 Continue
HTTP/1.1 100 Continue
HTTP/1.1 200 OK
Date: Wed, 18 Aug 2010 17:48:07 GMT
Server: Apache
ETag: "d358d5fd6360a736466600964195fcc6"
Cache-Control: private, max-age=0, must-revalidate
Content-Length: 4591
Status: 200
Content-Type: text/xml; charset=utf-8
Vary: Accept-Encoding

<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:tns="http://secure2.e-xact.com/vplug-in/transaction/rpc-enc/" xmlns:types="http://secure2.e-xact.com/vplug-in/transaction/rpc-enc/encodedTypes" xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/">
  <soap:Body soap:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
    <q1:SendAndCommitResponse xmlns:q1="http://secure2.e-xact.com/vplug-in/transaction/rpc-enc/Response">
      <SendAndCommitResult href="#id1">
      </SendAndCommitResult>
    </q1:SendAndCommitResponse>
    <types:TransactionResult id="id1" xsi:type="types:TransactionResult">
      <ExactID xsi:type="xsd:string">ExactID</ExactID>
      <Password xsi:nil="true"></Password>
      <Transaction_Type xsi:type="xsd:string">01</Transaction_Type>
      <DollarAmount xsi:type="xsd:string">15.75</DollarAmount>
      <SurchargeAmount xsi:nil="true"></SurchargeAmount>
      <Card_Number xsi:type="xsd:string">############1111</Card_Number>
      <Transaction_Tag xsi:type="xsd:string">901975484</Transaction_Tag>
      <Track1 xsi:nil="true"></Track1>
      <Track2 xsi:nil="true"></Track2>
      <PAN xsi:nil="true"></PAN>
      <Authorization_Num xsi:type="xsd:string">ET4653</Authorization_Num>
      <Expiry_Date xsi:type="xsd:string">1012</Expiry_Date>
      <CardHoldersName xsi:type="xsd:string">Donald Duck</CardHoldersName>
      <VerificationStr1 xsi:nil="true"></VerificationStr1>
      <VerificationStr2 xsi:nil="true"></VerificationStr2>
      <CVD_Presence_Ind xsi:type="xsd:string">0</CVD_Presence_Ind>
      <ZipCode xsi:nil="true"></ZipCode>
      <Tax1Amount xsi:nil="true"></Tax1Amount>
      <Tax1Number xsi:nil="true"></Tax1Number>
      <Tax2Amount xsi:nil="true"></Tax2Amount>
      <Tax2Number xsi:nil="true"></Tax2Number>
      <Secure_AuthRequired xsi:nil="true"></Secure_AuthRequired>
      <Secure_AuthResult xsi:nil="true"></Secure_AuthResult>
      <Ecommerce_Flag xsi:type="xsd:string">0</Ecommerce_Flag>
      <XID xsi:nil="true"></XID>
      <CAVV xsi:nil="true"></CAVV>
      <CAVV_Algorithm xsi:nil="true"></CAVV_Algorithm>
      <Reference_No xsi:nil="true"></Reference_No>
      <Customer_Ref xsi:nil="true"></Customer_Ref>
      <Reference_3 xsi:nil="true"></Reference_3>
      <Language xsi:nil="true"></Language>
      <Client_IP xsi:type="xsd:string">10.1.1.20</Client_IP>
      <Client_Email xsi:nil="true"></Client_Email>
      <LogonMessage xsi:nil="true"></LogonMessage>
      <Error_Number xsi:type="xsd:string">0</Error_Number>
      <Error_Description xsi:nil="true"> </Error_Description>
      <Transaction_Error xsi:type="xsd:boolean">false</Transaction_Error>
      <Transaction_Approved xsi:type="xsd:boolean">true</Transaction_Approved>
      <EXact_Resp_Code xsi:type="xsd:string">00</EXact_Resp_Code>
      <EXact_Message xsi:type="xsd:string">Transaction Normal</EXact_Message>
      <Bank_Resp_Code xsi:type="xsd:string">000</Bank_Resp_Code>
      <Bank_Message xsi:type="xsd:string">APPROVED</Bank_Message>
      <Bank_Resp_Code_2 xsi:nil="true"></Bank_Resp_Code_2>
      <SequenceNo xsi:type="xsd:string">025849</SequenceNo>
      <AVS xsi:nil="true"></AVS>
      <CVV2 xsi:nil="true"></CVV2>
      <Retrieval_Ref_No xsi:type="xsd:string">08184653</Retrieval_Ref_No>
      <CAVV_Response xsi:nil="true"></CAVV_Response>
      <MerchantName xsi:type="xsd:string">API Testing (Chase)</MerchantName>
      <MerchantAddress xsi:type="xsd:string">127 - 6768 Front St</MerchantAddress>
      <MerchantCity xsi:type="xsd:string">Vancouver</MerchantCity>
      <MerchantProvince xsi:type="xsd:string">British Columbia</MerchantProvince>
      <MerchantCountry xsi:type="xsd:string">Canada</MerchantCountry>
      <MerchantPostal xsi:type="xsd:string">V6B 2H7</MerchantPostal>
      <MerchantURL xsi:type="xsd:string">www.e-xact.com</MerchantURL>
      <CTR xsi:type="xsd:string">=========== TRANSACTION RECORD ==========
API Testing
127 - 6768 Front St
Vancouver, BC V6B 2H7
Canada
www.e-xact.com

TYPE: Pre-Authorization

ACCT: Visa  $ 15.75 CAD

CARD NUMBER : ############1111
DATE/TIME   : 18 Aug 10 09:46:52
REFERENCE # : 002 025849 M
AUTHOR. #   : ET4653
TRANS. REF. :

    Approved - Thank You 000


Please retain this copy for your records.

Cardholder will pay above amount to card
issuer pursuant to cardholder agreement.
=========================================</CTR>
    </types:TransactionResult>
  </soap:Body>
</soap:Envelope>

1.2.2 Example 2. Tagged Pre-Authorization Completion

This request illustrates the following:

  • using the REST API with XML message format
  • passing authentication credentials in the message as ExactID and Password properties
  • completing the Pre-Authorization transaction from Example 1 using the response properties from that transaction
curl -H 'Content-Type: application/xml; charset=UTF-8' \
     -H 'Accept: application/xml' \
     -d '<?xml version="1.0" encoding="UTF-8"?>
<Transaction>
  <ExactID>ExactID</ExactID>
  <Password>Password</Password>
  <Transaction_Type>32</Transaction_Type>
  <Transaction_Tag>901975484</Transaction_Tag>
  <Authorization_Num>ET4653</Authorization_Num>
  <DollarAmount>15.75</DollarAmount>
</Transaction>' \
https://api.e-xact.com/transaction

The resulting request headers and response:

POST /transaction HTTP/1.1
User-Agent: curl/7.21.0 (i386-apple-darwin9.8.0) libcurl/7.21.0 OpenSSL/1.0.0a zlib/1.2.5 libidn/1.19
Host: api.e-xact.com
Content-Type: application/xml; charset=UTF-8
Accept: application/xml
Content-Length: 304

HTTP/1.1 201 Created
Date: Wed, 18 Aug 2010 19:39:51 GMT
Server: Apache
Cache-Control: no-cache
Location: https://api.e-xact.com/transaction/v8.xml/902006933
Content-Length: 2573
Status: 201
Content-Type: application/xml; charset=utf-8
Vary: Accept-Encoding

<?xml version="1.0" encoding="UTF-8"?>
<TransactionResult>
  <ExactID>ExactID</ExactID>
  <Password></Password>
  <Transaction_Type>32</Transaction_Type>
  <DollarAmount>15.75</DollarAmount>
  <SurchargeAmount></SurchargeAmount>
  <Card_Number>############1111</Card_Number>
  <Transaction_Tag>902006933</Transaction_Tag>
  <Track1></Track1>
  <Track2></Track2>
  <PAN></PAN>
  <Authorization_Num>ET4653</Authorization_Num>
  <Expiry_Date>1012</Expiry_Date>
  <CardHoldersName>Donald Duck</CardHoldersName>
  <VerificationStr1></VerificationStr1>
  <VerificationStr2></VerificationStr2>
  <CVD_Presence_Ind>0</CVD_Presence_Ind>
  <ZipCode></ZipCode>
  <Tax1Amount></Tax1Amount>
  <Tax1Number></Tax1Number>
  <Tax2Amount></Tax2Amount>
  <Tax2Number></Tax2Number>
  <Secure_AuthRequired></Secure_AuthRequired>
  <Secure_AuthResult></Secure_AuthResult>
  <Ecommerce_Flag>0</Ecommerce_Flag>
  <XID></XID>
  <CAVV></CAVV>
  <CAVV_Algorithm></CAVV_Algorithm>
  <Reference_No></Reference_No>
  <Customer_Ref></Customer_Ref>
  <Reference_3></Reference_3>
  <Language></Language>
  <Client_IP>10.1.1.20</Client_IP>
  <Client_Email></Client_Email>
  <LogonMessage></LogonMessage>
  <Error_Number>0</Error_Number>
  <Error_Description> </Error_Description>
  <Transaction_Error>false</Transaction_Error>
  <Transaction_Approved>true</Transaction_Approved>
  <EXact_Resp_Code>00</EXact_Resp_Code>
  <EXact_Message>Transaction Normal</EXact_Message>
  <Bank_Resp_Code>000</Bank_Resp_Code>
  <Bank_Message>APPROVED</Bank_Message>
  <Bank_Resp_Code_2></Bank_Resp_Code_2>
  <SequenceNo>025850</SequenceNo>
  <AVS></AVS>
  <CVV2></CVV2>
  <Retrieval_Ref_No>08183837</Retrieval_Ref_No>
  <CAVV_Response></CAVV_Response>
  <MerchantName>API Testing (Chase)</MerchantName>
  <MerchantAddress>127 - 6768 Front St</MerchantAddress>
  <MerchantCity>Vancouver</MerchantCity>
  <MerchantProvince>British Columbia</MerchantProvince>
  <MerchantCountry>Canada</MerchantCountry>
  <MerchantPostal>V6B 2H7</MerchantPostal>
  <MerchantURL>www.e-xact.com</MerchantURL>
  <CTR>=========== TRANSACTION RECORD ==========
API Testing
127 - 6768 Front St
Vancouver, BC V6B 2H7
Canada
www.e-xact.com

TYPE: Pre-Auth Completion

ACCT: Visa  $ 15.75 CAD

CARD NUMBER : ############1111
DATE/TIME   : 18 Aug 10 11:38:36
REFERENCE # : 002 025850 M
AUTHOR. #   : ET4653
TRANS. REF. :

    Approved - Thank You 000


Please retain this copy for your records.

Cardholder will pay above amount to card
issuer pursuant to cardholder agreement.
=========================================</CTR>
</TransactionResult>

1.2.3 Example 3. Tagged Refund

This request illustrates the following:

  • using the REST API with JSON message format
  • passing authentication credentials as HTTP Basic Authentication username:password values
  • refunding the Tagged Pre-Authorization Completion transaction from Example 2 using the response properties from that transaction
curl -u 'ExactID:Password' \
     -H 'Content-Type: application/json; charset=UTF-8' \
     -H 'Accept: application/json' \
     -d '{
 "transaction_type":"34",
 "transaction_tag":"902006933",
 "authorization_num":"ET4653",
 "amount":"15.75"
}' \
https://api.e-xact.com/transaction

The resulting request headers and response:

POST /transaction HTTP/1.1
Authorization: Basic Foo4BarBazAyOjAhcGl0ZXN0
User-Agent: curl/7.21.0 (i386-apple-darwin9.8.0) libcurl/7.21.0 OpenSSL/1.0.0a zlib/1.2.5 libidn/1.19
Host: api.e-xact.com
Content-Type: application/json; charset=UTF-8
Accept: application/json
Content-Length: 110

HTTP/1.1 201 Created
Date: Wed, 18 Aug 2010 19:52:18 GMT
Server: Apache
Cache-Control: no-cache
Location: https://api.e-xact.com/transaction?amount=15.75&authorization_num=ET4653&transaction_tag=902006933&transaction_type=34/902010341
Content-Length: 1713
Status: 201
Content-Type: application/json; charset=utf-8
Vary: Accept-Encoding

{"merchant_url":"www.e-xact.com",
"cc_number":"############1111",
"secure_auth_required":null,
"cc_verification_str2":null,
"zip_code":null,
"user_name":null,
"reference_no":null,
"cc_expiry":"1012",
"avs":null,
"client_email":null,
"secure_auth_result":null,
"cavv_response":null,
"bank_resp_code":"000",
"password":null,
"merchant_address":"127 - 6768 Front St",
"transaction_tag":902010341,
"cardholder_name":"Donald Duck",
"retrieval_ref_no":"08185104",
"gateway_id":"ExactID",
"merchant_country":"Canada",
"error_description":" ",
"bank_message":"APPROVED",
"cavv":null,
"track1":null,
"tax1_amount":null,
"reference_3":null,
"surcharge_amount":null,
"transaction_type":"34",
"ctr":"=========== TRANSACTION RECORD ==========\nAPI Testing\n127 - 6768 Front St\nVancouver, BC V6B 2H7\nCanada\nwww.e-xact.com\n\nTYPE: Refund\n\nACCT: Visa  $ 15.75 CAD\n\nCARD NUMBER : ############1111\nDATE/TIME   : 18 Aug 10 11:51:03\nREFERENCE # : 002 025851 M\nAUTHOR. #   : RETURN\nTRANS. REF. : \n\n    Approved - Thank You 000\n\n\nPlease retain this copy for your records.\n\n=========================================",
"ecommerce_flag":0,
"bank_resp_code_2":null,
"language":null,
"merchant_city":"Vancouver",
"logon_message":null,
"tax2_amount":null,
"track2":null,
"transaction_approved":1,
"merchant_postal":"V6B 2H7",
"transaction_error":0,
"cvd_presence_ind":0,
"xid":null,
"pan":null,
"tax1_number":null,
"exact_resp_code":"00",
"customer_ref":null,
"amount":15.75,
"cavv_algorithm":null,
"cvv2":null,
"cc_verification_str1":null,
"sequence_no":"025851",
"merchant_name":"API Testing (Chase)",
"client_ip":"10.1.1.20",
"merchant_province":"British Columbia",
"error_number":0,
"tax2_number":null,
"authorization_num":"RETURN",
"exact_message":"Transaction Normal"}

1.3 Client Libraries

cURL is good for a quick test, but once you are ready to develop an application, check out the nice client libraries from E-xact:

  • ruby - exact4r
    • homepage: http://exact4r.rubyforge.org/
    • available as a ruby gem (https://rubygems.org/gems/exact4r/)
  • java - exact4j
    • homepage: https://github.com/exact/exact4j/wiki/

2 Transaction Processing Scenarios

When processing a transaction, various properties are required, optional and not used.  A processing scenario defines these requirements. Two factors define the processing scenarios that are possible:

  • credit card number source - the property used to define the credit card number
  • transaction type - Purchase, Refund, etc.

For each credit card number source, certain transactions types can be processed.  All of the possible processing scenarios are defined in the tables listed below, where each table shows one credit card number source and the corresponding possible transaction types:

credit card number source
processing scenario table
Card_Number Table 1.1
Transaction_Tag (Defines a tag which references a stored credit card number) Table 1.2
Track1 Table 1.3
Track2 Table 1.4

NOTE: To prevent errors when processing, the credit card number should be defined using only one of the above properties.

A black background in each table is used to identify the source and transaction types being described. Each possible processing scenario is defined by matching a black column (credit card source) and black row (transaction type).

The properties that are required, optional and not used to process a transaction are defined along the row for the selected transaction type. Required properties are in red (x). Optional properties are in green (/). Properties not used are blank. The 3-D Secure properties are not included.

All other properties can be populated, even if they are not used for processing.

Table_1.1.png
Table_1.2.png
Table_1.3.png
Table_1.4.png

Request Properties

Only some of the following properties are required, depending on the processing scenario being used. Refer to the Processing Scenarios section for more information on which properties are required for each particular scenario.  The value for a property should be a string conforming to the data type (i.e. Null, String, Integer etc.) indicated below. Note that a small number of the parameters have different names when using the JSON format.

Property

Description
ExactID
  • String [10]
  • {Read/Write} {minOccurs="1" maxOccurs="1"}
gateway_id (JSON format)
Identifies the location/terminal that is sending the transaction. This number is of the format Axxxxx-xx and is provided by E-xact upon set-up. The ExactID must be accompanied by a password.
Password
  • String [30]
  • {Read/Write} {minOccurs="1" maxOccurs="1"}
password (JSON format)
Password that is uniquely associated with each ExactID. This value must be kept as secure (and secret) as possible.
Transaction_Type
  • String [2]
  • {Read/Write} {minOccurs=”1” maxOccurs=”1”}
transaction_type (JSON format)
Populated with a two-digit string indicator. The indicator identifies the transaction type. Descriptions of these transaction types can be found here. Supported values include:
  • 00 = Purchase
  • 01 = Pre-Authorization
  • 02 = Pre-Authorization Completion
  • 03 = Forced Post
  • 04 = Refund
  • 05 = Pre-Authorization Only**
  • 11 = Purchase Correction***
  • 12 = Refund Correction***
  • 13 = Void
  • 30 = Tagged Purchase
  • 31 = Tagged Pre-Authorization
  • 32 = Tagged Pre-Authorization Completion
  • 33 = Tagged Void
  • 34 = Tagged Refund
  • 35 = Tagged Online Debit Refund
  • 40 = Recurring Seed
  • 41 = Recurring Seed Purchase
  • 50 = Debit Purchase
  • 54 = Debit Refund
  • 60 = Secure Storage
  • CR = Information Retrieval
** Only Telus supports the Transaction Type.
*** Only Moneris supports the Transaction Type.
DollarAmount
  • Double [99,999.99]
  • {Read/Write} {minOccurs="1" maxOccurs="1"}
amount (JSON format)
The amount of the transaction in dollars and cents.
SurchargeAmount
  • Double [99,999.99]
  • {Read/Write} {minOccurs="1" maxOccurs="1"}
surcharge_amount (JSON format)
Additional amount for iDebit fee (optional). This amount is added to the DollarAmount of the transaction and used in iDebit transactions only
Card_Number
  • String [16]
  • {Read/Write} {minOccurs=”0” maxOccurs=”1”}
cc_number (JSON format)
The customer’s credit card number. Not used for tagged transaction types.
Transaction_Tag
  • Integer
  • {Read/Write} {minOccurs=”0” maxOccurs=”1”}
transaction_tag (JSON format)
A unique identifier to associate with a tagged transaction. Only for tagged transaction types.
Track1
  • String [75]
  • {Read/Write} {minOccurs=”0” maxOccurs=”1”}
track1 (JSON format)
Populated with the unmodified track 1 data swiped from a valid credit card. Start and end sentinels are not included. Only for swiped transactions.
Track2
  • String
  • {Read/Write } {minOccurs=”0” maxOccurs=”1”}
track2 (JSON format)
Populated with the unmodified track 2 data swiped from a valid credit card. Start and end sentinels are not included. Only for swiped transactions.
PAN
  • String [37]
  • {Read/Write } {minOccurs=”1” maxOccurs=”1”}
pan (JSON format)
Verification data received from Acxsys after cardholder processes iDebit purchase with participating bank. Used in iDebit transactions only
Authorization_Num
  • String [8]
  • {Read/Write} {minOccurs=”0” maxOccurs=”1”}
authorization_num (JSON format)
This is the authorization number returned by the cardholder’s financial institution when a transaction has been approved. This value needs to be sent when sending various transaction types such as preauthorization completion, void, purchase correction, refund correction, or tagged transaction.
Expiry_Date
  • String [4]
  • {Read/Write} {minOccurs=”0” maxOccurs=”1”}
cc_expiry (JSON format)
The credit card expiry date in the format mmyy. Property for manually entering expiry date. If Track1 or Track2 is populated, there is no need to set this field.
CardHoldersName
  • String [30]
  • {Read/Write} {minOccurs=”0” maxOccurs=”1”}
cardholder_name (JSON format)
The customer’s name. The following characters will be stripped from this field: ; ` " / % as well as -- (2 consecutive dashes).
VerificationStr1
  • String [41]
  • {Read/Write} {minOccurs=”0” maxOccurs=”1”}
cc_verification_str1 (JSON format)
This string is supported by US and CAD financial institutions. It is populated with the cardholders address information in a specific format. The address is verified and a result is returned (AVS property) that indicates how well the address matched. Please contact E-xact for further information on address verification if it is applicable.
VerificationStr2
  • String [4]
  • {Read/Write} {minOccurs=”0” maxOccurs=”1”}
cc_verification_str2 (JSON format)
This is the 0, 3, or 4-digit code on the back of the credit card sometimes called the CVV2 or CVD value.
CVD_Presence_Ind
  • String [1]
  • {Read/Write} {minOccurs=”0” maxOccurs=”1”}
cvd_presence_ind (JSON format)
The number indicates how the CVV2 value should be handled when processing. The value must be either null or the integer 0, 1, 2, or 9. Note that null defaults to 0.
  • Null or 0 = Not Supported (Default)
  • 1 = Value provided by Cardholder
  • 2 = Value provided on card is Illegible
  • 9 = Cardholder states data is not available
Reference_No
  • String [20]
  • {Read/Write} {minOccurs=”0” maxOccurs=”1”}
reference_no (JSON format)
A merchant defined value that can be used to internally identify the transaction. This value is passed through to E-xact’s Gateway unmodified, and may be searched in E-xact’s Payment Manager (via E-xact’s website). It is not passed on to the financial institution. The following characters will be stripped from this field: ; ` " / % as well as -- (2 consecutive dashes).
ZipCode
  • String [10]
  • {Write} {minOccurs=”1” maxOccurs=”1”}
zip_code (JSON format)
Customer zip code used for qualifying transactions, only applicable to merchants passing level 2 (Corporate Credit Card) data
Tax1Amount
  • Double [99,999.99]
  • {Write} {minOccurs=”1” maxOccurs=”1”}
tax1_amount (JSON format)
Tax value included in total amount, only applicable to merchants passing level 2 (Corporate Credit Card) data. For Canadian merchants this field is the PST amount.
Tax1Number
  • String [20]
  • {Write} {minOccurs=”1” maxOccurs=”1”}
tax1_number (JSON format)
Registered number associated with the tax value. Used for reference or government claims purposes and only applicable to merchants passing level 2 (Corporate Credit Card) data. For Canadian merchants this field is the PST number.
Tax2Amount
  • Double [99,999.99]
  • {Write} {minOccurs=”1” maxOccurs=”1”}
tax2_amount (JSON format)
Tax value included in total amount, only applicable to merchants passing level 2 (Corporate Credit Card) data. For Canadian merchants this field is the GST amount.
Tax2Number
  • String [20]
  • {Write} {minOccurs=”1” maxOccurs=”1”}
tax2_number (JSON format)
Registered number associated with the tax value. Used for reference or government claims purposes and only applicable to merchants passing level 2 (Corporate Credit Card) data. For Canadian merchants this field is the GST number.
Customer_Ref
  • String [20]
  • {Read/Write} {minOccurs=”0” maxOccurs=”1”}
customer_ref (JSON format)
A merchant defined value that can be used to internally identify the transaction. This value is passed through to E-xact’s Gateway unmodified, and may be searched in E-xact’s Payment Manager (via E-xact’s website). It is not passed on to the financial institution. The following characters will be stripped from this field: ; ` " / % as well as -- (2 consecutive dashes).
Reference_3
  • Char [30]
  • {Read/Write} {minOccurs=”0” maxOccurs=”1”}
reference_3 (JSON format)
A merchant defined value that can be used to internally identify the transaction. This value is passed through to E-xact’s Gateway unmodified. It is not searchable and is not passed on to the financial institution. The following characters will be stripped from this field: ; ` " / % as well as -- (2 consecutive dashes).
Language
  • Integer
  • {Read/Write} {minOccurs=”0” maxOccurs=”1”}
language (JSON format)
Selects the language the CTR is to appear in. Supported Values:
  • EN {Default}
  • FR
Client_IP
  • String [15]
  • {Read/Write} {minOccurs=”0” maxOccurs=”1”}
client_ip (JSON format)
This is the IP address of the customer (i.e. client browser) connecting to the merchant. This value is stored for fraud investigation. It is not passed on to the financial institution.
Client_Email
  • String [30]
  • {Read/Write} {minOccurs=”0” maxOccurs=”1”}
client_email (JSON format)
This is the email address of the customer connecting to the merchant. This value is stored for fraud investigation. It is not passed on to the financial institution.
CAVV
  • String [var]
  • {Read/Write} {minOccurs=”0” maxOccurs=”1”}
cavv (JSON format)
3-D Secure/Verified by Visa value returned by Cardinal Commerce.
XID
  • String [var]
  • {Read/Write} {minOccurs=”0” maxOccurs=”1”}
xid (JSON format)
 3-D Secure/Verified by Visa value returned by Cardinal Commerce.

Ecommerce_Flag

  • String [var]
  • {Read/Write} {minOccurs=”0” maxOccurs=”1”}
ecommerce_flag (JSON format)
Should be set to "5" if the cardholder was fully authorized by 3-D Secure/Verified by Visa or "6" if the cardholder chose not to participate.

 

4 Response Properties

The following properties are returned in the response. In addition, all the Request Properties are also returned. The Request Properties returned in the Response are populated with the values actually used to process the transaction. Any changes made to a Request Property while processing will be reflected by the altered return value. In addition, the Request Properties Transaction_Tag and Authorization_Num are overridden by new return values. The new values reference the new transaction that has been processed.

Property Description
LogonMessage
  • String [255]
  • {Read} {minOccurs=”0” maxOccurs=”1”}
Returned by E-xact upon successful Authentication. Indicates the location and version of the server that provided authentication.
Error_Number
  • Integer
  • {Read} {minOccurs=”1” maxOccurs=”1”}
This property indicates an error was encountered while processing the transaction. If no errors were encountered, a value of zero will be returned. The Transaction_Error property will return True if this property is not zero. Please refer to the section on Exception Handling for further information.
Error_Description
  • String[var]
  • {Read} {minOccurs=”0” maxOccurs=”1”}
A message that accompanies the Error_Number, if an error occurred. Please refer to the section on Exception Handling for further information.
Transaction_Error
  • Boolean
  • {Read} {minOccurs=”1” maxOccurs=”1”}
This property indicates that there was an error during the processing of the transaction. Please refer to E-xact Response Codes (ETG Codes) for further information.
Transaction_Approved
  • Boolean
  • {Read} {minOccurs=”1” maxOccurs=”1”}
This property indicates that the bank approved a transaction and there are no pending errors. If further information is required, please check the Optional Response properties.
Exact_Resp_code
  • String [2]
  • {Read} {minOccurs=”0” maxOccurs=”1”}
This property indicates the processing status of the transaction. Please refer to the section on Exception Handling for further information. The Transaction_Error property will return True if this property is not “00”.
Exact_Message
  • String [50]
  • {Read} {minOccurs=”0” maxOccurs=”1”}
Message that accompanies the Exact_Resp_code.
Bank_Resp_code
  • String [3]
  • {Read} {minOccurs=”0” maxOccurs=”1”}
This is a 2 or 3 digit code, provided by the financial institution, indicating the approval status of a transaction. The meaning of these codes is defined by the various financial institutions and is not under the control of the API or Gateway. Please refer to the Transaction_Approved property for the approval status of a transaction.
Bank_Message
  • String [80]
  • {Read} {minOccurs=”0” maxOccurs=”1”}
A message provided by the financial institution describing the Response code above.
Bank_Resp_code_2
  • String [2]
  • {Read} {minOccurs=”0” maxOccurs=”1”}
A secondary response provided returned by the financial institution.
Transaction_Tag
  • Integer
  • {Read/Write} {minOccurs=”0” maxOccurs=”1”}
A unique identifier to associate with a tagged transaction. This value overrides any value sent for the Request Property of the same name.
Authorization_Num
  • String [8]
  • {Read/Write} {minOccurs=”0” maxOccurs=”1”}
This is the authorization number returned by the cardholder’s financial institution when a transaction has been approved. This value overrides any value sent for the Request Property of the same name.
SequenceNo
  • String [50]
  • {Read} {minOccurs=”0” maxOccurs=”1”}
An n digit sequentially incremented number generated by E-xact and passed through to the financial institution. It is also passed back to the client in the transaction response. This number can be used for tracking and audit purposes.
AVS
  • String [1]
  • {Read} {minOccurs=”0” maxOccurs=”1”}
Supported AVS Results:
  • X = exact match, 9 digit zip
  • Y = exact match, 5 digit zip
  • A = address match only
  • W = 9 digit zip match only
  • Z = 5 digit zip match only
  • N = no address or zip match
  • U = address unavailable
  • G = non-North American issuer, does not participate
  • R = issuer system unavailable
  • E = not a Mail\Phone order
  • S = service not supported
CVV2
  • String [1]
  • {Read} {minOccurs=”0” maxOccurs=”1”}
The CVV2 authentication code returned from the bank. Note: the value is null if CVV2 is not supported.
Supported CVV Results:
  • M = CVV2 / CVC2/CVD Match.
  • N = CVV2 / CVC2/CVD No Match.
  • P = Not Processed.
  • S = Merchant has indicated that CVV2 / CVC2/CVD is not present on the card.
  • U = Issuer is not certified and / or has not provided Visa encryption keys.
Retrieval_Ref_No
  • String [13]
  • {Read} {minOccurs=”0” maxOccurs=”1”}
The reference number returned with an AVS Result.
MerchantName
  • String [50]
  • {Read} {minOccurs=”0” maxOccurs=”1”}
Returned by E-xact upon successful Authentication.
MerchantAddress
  • String [50]
  • {Read} {minOccurs=”0” maxOccurs=”1”}
Returned by E-xact upon successful Authentication.
MerchantCity
  • String [25]
  • {Read} {minOccurs=”0” maxOccurs=”1”}
Returned by E-xact upon successful Authentication.
MerchantProvince
  • String [2]
  • {Read} {minOccurs=”0” maxOccurs=”1”}
Returned by E-xact upon successful Authentication.
MerchantCountry
  • String [50]
  • {Read
Returned by E-xact upon successful Authentication.
MerchantPostal
  • String [12]
  • {Read} {minOccurs=”0” maxOccurs=”1”}
Returned by E-xact upon successful Authentication.
MerchantURL
  • String [25]
  • {Read} {minOccurs=”0” maxOccurs=”1”}
Returned by E-xact upon successful Authentication.
CTR
  • String [var]
  • {Read} {minOccurs=”0” maxOccurs=”1”}
Displays the bank required Customer Transaction Record. This information must be displayed to the customer upon completion of all transactions, Approved or Declined.

5 SOAP Message Format

The SOAP style API uses an RPC/Encoded message as defined in the SOAP 1.1 protocol. The RPC/Encoded standard is supported by virtually all software implementations of SOAP.

The RPC/Encoded standard does allow for some variation to occur within the formatting of a SOAP message. This can occur with both the Request and Response, and the API handles these variations in a predictable way. The following sections on Request Message Format and Response Message Format describes some of the variations that can occur with the SOAP message.

The World Wide Web Consortium defines the standard for the RPC/Encoded protocol. Documentation on it can be found at http://www.w3.org/TR/2000/NOTE-SOAP-20000508.

5.1 Request Message Format

The API is able to handle certain variations in the SOAP message format for the Request. The greatest variation supported is in how the Transactions struct is defined in the Request message.

Referencing or embedding may be used to define the Transaction struct element. The Transaction struct can be defined by referencing it within the Process element. Example 5.1 provides an example of a Request message that uses a referenced Transaction struct. This example is also online at:

http://api.e-xact.com/vplug-in/transaction/rpc-enc/service.asmx?op=Process

The Transaction struct can also be defined by embedding it within the Process element. Example 5.2 provides an example of a Request message that uses an embedded Transaction struct.

If correctly formatted, referencing or embedding the Transaction struct element will result in the same Response being returned. The response returned is described in the section Response Message Format.

NOTE: The placeholders "string" and "boolean" in the examples would need to be replaced with actual values.

Example 5.1 SOAP Request Message with a Referenced Transaction Struct

POST /vplug-in/transaction/rpc-enc/service.asmx HTTP/1.1
Host: api.e-xact.com
Content-Type: text/xml; charset=utf-8
Content-Length: length
SOAPAction: http://api.e-xact.com/vplug-in/transaction/rpc-enc/SendAndCommit

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:tns="http://api.e-xact.com/vplug-in/transaction/rpc-enc/"
xmlns:types="http://api.e-xact.com/vplug-in/transaction/rpc-enc/encodedTypes"
xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body soap:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
    <q1:SendAndCommit xmlns:q1="http://api.e-xact.com/vplug-in/transaction/rpc-enc/Request">
      <SendAndCommitSource href="#id1" />
    </q1:SendAndCommit>
    <types:Transaction id="id1" xsi:type="types:Transaction">
      <ExactID xsi:type="xsd:string">string</ExactID>
      <Password xsi:type="xsd:string">string</Password>
      <Transaction_Type xsi:type="xsd:string">string</Transaction_Type>
      <DollarAmount xsi:type="xsd:string">string</DollarAmount>
      <SurchargeAmount xsi:type="xsd:string">string</SurchargeAmount>
      <Card_Number xsi:type="xsd:string">string</Card_Number>
      <Transaction_Tag xsi:type="xsd:string">string</Transaction_Tag>
      <Track1 xsi:type="xsd:string">string</Track1>
      <Track2 xsi:type="xsd:string">string</Track2>
      <PAN xsi:type="xsd:string">string</PAN>
      <Authorization_Num xsi:type="xsd:string">string</Authorization_Num>
      <Expiry_Date xsi:type="xsd:string">string</Expiry_Date>
      <CardHoldersName xsi:type="xsd:string">string</CardHoldersName>
      <VerificationStr1 xsi:type="xsd:string">string</VerificationStr1>
      <VerificationStr2 xsi:type="xsd:string">string</VerificationStr2>
      <CVD_Presence_Ind xsi:type="xsd:string">string</CVD_Presence_Ind>
      <ZipCode xsi:type="xsd:string">string</ZipCode>
      <Tax1Amount xsi:type="xsd:string">string</Tax1Amount>
      <Tax1Number xsi:type="xsd:string">string</Tax1Number>
      <Tax2Amount xsi:type="xsd:string">string</Tax2Amount>
      <Tax2Number xsi:type="xsd:string">string</Tax2Number>
      <Secure_AuthRequired xsi:type="xsd:string">string</Secure_AuthRequired>
      <Secure_AuthResult xsi:type="xsd:string">string</Secure_AuthResult>
      <Ecommerce_Flag xsi:type="xsd:string">string</Ecommerce_Flag>
      <XID xsi:type="xsd:string">string</XID>
      <CAVV xsi:type="xsd:string">string</CAVV>
      <CAVV_Algorithm xsi:type="xsd:string">string</CAVV_Algorithm>
      <Reference_No xsi:type="xsd:string">string</Reference_No>
      <Customer_Ref xsi:type="xsd:string">string</Customer_Ref>
      <Reference_3 xsi:type="xsd:string">string</Reference_3>
      <Language xsi:type="xsd:string">string</Language>
      <Client_IP xsi:type="xsd:string">string</Client_IP>
      <Client_Email xsi:type="xsd:string">string</Client_Email>
    </types:Transaction>
  </soap:Body>
</soap:Envelope>

Example 5.2 SOAP Request Message with an Embedded Transaction Struct

POST /vplug-in/transaction/rpc-enc/service.asmx HTTP/1.1
Host: api.e-xact.com
Content-Type: text/xml; charset=utf-8
Content-Length: length
SOAPAction: http://api.e-xact.com/vplug-in/transaction/rpc-enc/SendAndCommit

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:tns="http://api.e-xact.com/vplug-in/transaction/rpc-enc/"
xmlns:types="http://api.e-xact.com/vplug-in/transaction/rpc-enc/encodedTypes"
xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body soap:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
    <q1:SendAndCommit xmlns:q1="http://api.e-xact.com/vplug-in/transaction/rpc-enc/Request"
    soap:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
    <types:Transaction id="id1" xsi:type="types:Transaction">
      <ExactID xsi:type="xsd:string">string</ExactID>
      <Password xsi:type="xsd:string">string</Password>
      <Transaction_Type xsi:type="xsd:string">string</Transaction_Type>
      <DollarAmount xsi:type="xsd:string">string</DollarAmount>
      <SurchargeAmount xsi:type="xsd:string">string</SurchargeAmount>
      <Card_Number xsi:type="xsd:string">string</Card_Number>
      <Transaction_Tag xsi:type="xsd:string">string</Transaction_Tag>
      <Track1 xsi:type="xsd:string">string</Track1>
      <Track2 xsi:type="xsd:string">string</Track2>
      <PAN xsi:type="xsd:string">string</PAN>
      <Authorization_Num xsi:type="xsd:string">string</Authorization_Num>
      <Expiry_Date xsi:type="xsd:string">string</Expiry_Date>
      <CardHoldersName xsi:type="xsd:string">string</CardHoldersName>
      <VerificationStr1 xsi:type="xsd:string">string</VerificationStr1>
      <VerificationStr2 xsi:type="xsd:string">string</VerificationStr2>
      <CVD_Presence_Ind xsi:type="xsd:string">string</CVD_Presence_Ind>
      <ZipCode xsi:type="xsd:string">string</ZipCode>
      <Tax1Amount xsi:type="xsd:string">string</Tax1Amount>
      <Tax1Number xsi:type="xsd:string">string</Tax1Number>
      <Tax2Amount xsi:type="xsd:string">string</Tax2Amount>
      <Tax2Number xsi:type="xsd:string">string</Tax2Number>
      <Secure_AuthRequired xsi:type="xsd:string">string</Secure_AuthRequired>
      <Secure_AuthResult xsi:type="xsd:string">string</Secure_AuthResult>
      <Ecommerce_Flag xsi:type="xsd:string">string</Ecommerce_Flag>
      <XID xsi:type="xsd:string">string</XID>
      <CAVV xsi:type="xsd:string">string</CAVV>
      <CAVV_Algorithm xsi:type="xsd:string">string</CAVV_Algorithm>
      <Reference_No xsi:type="xsd:string">string</Reference_No>
      <Customer_Ref xsi:type="xsd:string">string</Customer_Ref>
      <Reference_3 xsi:type="xsd:string">string</Reference_3>
      <Language xsi:type="xsd:string">string</Language>
      <Client_IP xsi:type="xsd:string">string</Client_IP>
      <Client_Email xsi:type="xsd:string">string</Client_Email>
    </types:Transaction>
    </q1:SendAndCommit>
  </soap:Body>
</soap:Envelope>

5.2 Response Message Format

The Request message format allowed the Transaction struct to either be referenced or embedded. The TransactionResult struct returned in the Response message is always defined by reference. Example 5.3 provides an example of a Response message that would be returned for both Example’s 5.1 and 5.2.

NOTE: The placeholders "string" and "boolean" in the examples would need to be replaced with actual values.

Example 5.3 SOAP Response Message with a Referenced TransactionResult Struct

HTTP/1.1 200 OK
Content-Type: text/xml; charset=utf-8
Content-Length: length

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:tns="http://api.e-xact.com/vplug-in/transaction/rpc-enc/"
xmlns:types="http://api.e-xact.com/vplug-in/transaction/rpc-enc/encodedTypes"
xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body soap:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
    <q3:SendAndCommitResponse xmlns:q3="http://api.e-xact.com/vplug-in/transaction/rpc-enc/Response">
      <SendAndCommitResult href="#id1" />
    </q3:SendAndCommitResponse>
    <types:TransactionResult id="id1" xsi:type="types:TransactionResult">
      <ExactID xsi:type="xsd:string">string</ExactID>
      <Password xsi:type="xsd:string">string</Password>
      <Transaction_Type xsi:type="xsd:string">string</Transaction_Type>
      <DollarAmount xsi:type="xsd:string">string</DollarAmount>
      <SurchargeAmount xsi:type="xsd:string">string</SurchargeAmount>
      <Card_Number xsi:type="xsd:string">string</Card_Number>
      <Transaction_Tag xsi:type="xsd:string">string</Transaction_Tag>
      <Track1 xsi:type="xsd:string">string</Track1>
      <Track2 xsi:type="xsd:string">string</Track2>
      <PAN xsi:type="xsd:string">string</PAN>
      <Authorization_Num xsi:type="xsd:string">string</Authorization_Num>
      <Expiry_Date xsi:type="xsd:string">string</Expiry_Date>
      <CardHoldersName xsi:type="xsd:string">string</CardHoldersName>
      <VerificationStr1 xsi:type="xsd:string">string</VerificationStr1>
      <VerificationStr2 xsi:type="xsd:string">string</VerificationStr2>
      <CVD_Presence_Ind xsi:type="xsd:string">string</CVD_Presence_Ind>
      <ZipCode xsi:type="xsd:string">string</ZipCode>
      <Tax1Amount xsi:type="xsd:string">string</Tax1Amount>
      <Tax1Number xsi:type="xsd:string">string</Tax1Number>
      <Tax2Amount xsi:type="xsd:string">string</Tax2Amount>
      <Tax2Number xsi:type="xsd:string">string</Tax2Number>
      <Secure_AuthRequired xsi:type="xsd:string">string</Secure_AuthRequired>
      <Secure_AuthResult xsi:type="xsd:string">string</Secure_AuthResult>
      <Ecommerce_Flag xsi:type="xsd:string">string</Ecommerce_Flag>
      <XID xsi:type="xsd:string">string</XID>
      <CAVV xsi:type="xsd:string">string</CAVV>
      <CAVV_Algorithm xsi:type="xsd:string">string</CAVV_Algorithm>
      <Reference_No xsi:type="xsd:string">string</Reference_No>
      <Customer_Ref xsi:type="xsd:string">string</Customer_Ref>
      <Reference_3 xsi:type="xsd:string">string</Reference_3>
      <Language xsi:type="xsd:string">string</Language>
      <Client_IP xsi:type="xsd:string">string</Client_IP>
      <Client_Email xsi:type="xsd:string">string</Client_Email>
      <LogonMessage xsi:type="xsd:string">string</LogonMessage>
      <Error_Number xsi:type="xsd:string">string</Error_Number>
      <Error_Description xsi:type="xsd:string">string</Error_Description>
      <Transaction_Error xsi:type="xsd:boolean">boolean</Transaction_Error>
      <Transaction_Approved xsi:type="xsd:boolean">boolean</Transaction_Approved>
      <EXact_Resp_Code xsi:type="xsd:string">string</EXact_Resp_Code>
      <EXact_Message xsi:type="xsd:string">string</EXact_Message>
      <Bank_Resp_Code xsi:type="xsd:string">string</Bank_Resp_Code>
      <Bank_Message xsi:type="xsd:string">string</Bank_Message>
      <Bank_Resp_Code_2 xsi:type="xsd:string">string</Bank_Resp_Code_2>
      <SequenceNo xsi:type="xsd:string">string</SequenceNo>
      <AVS xsi:type="xsd:string">string</AVS>
      <CVV2 xsi:type="xsd:string">string</CVV2>
      <Retrieval_Ref_No xsi:type="xsd:string">string</Retrieval_Ref_No>
      <CAVV_Response xsi:type="xsd:string">string</CAVV_Response>
      <MerchantName xsi:type="xsd:string">string</MerchantName>
      <MerchantAddress xsi:type="xsd:string">string</MerchantAddress>
      <MerchantCity xsi:type="xsd:string">string</MerchantCity>
      <MerchantProvince xsi:type="xsd:string">string</MerchantProvince>
      <MerchantCountry xsi:type="xsd:string">string</MerchantCountry>
      <MerchantPostal xsi:type="xsd:string">string</MerchantPostal>
      <MerchantURL xsi:type="xsd:string">string</MerchantURL>
      <CTR xsi:type="xsd:string">string</CTR>
    </types:TransactionResult>
  </soap:Body>
</soap:Envelope>

Certain variations can occur in the SOAP message format for the Response. Variations in the message may occur in three general ways. The variations may occur if a SOAP exception is thrown, in the way the child elements are ordered in the TransactionResult struct and in the addition of new elements to the TransactionResult struct.

The first way in which the Response message may vary is if a SOAP exception is returned. This type of response is returned to indicate an error. The SOAP exception message format is completely different from a normal Response. The conditions under which a SOAP exception may occur and the format of the message sent are described in the Exception Handling section.

The second way in which the Response message may vary is in the order of the child elements contained within the TransactionResult struct. The TransactionResult struct is a complex data type. There are no requirements in the RPC/Encoded standard for the contents of such a data type to follow a fixed sequence. Overtime and with modifications to the Payment Web Service, the order of the child elements contained within the TransactionResult struct may change.

The third way in which the Response message may vary is with the addition of new child elements contained within the TransactionResult struct. With upgrades to the Payment Web Service to allow enhanced processing capabilities, the complex data type may be expanded to support additional properties. When this occurs, new elements would be automatically added to the TransactionResult struc. The existing properties / elements would always continue to be supported.

6 Exception Handling

The API may return error messages in two different forms. An error message is either returned as a Soap Exception or as Response - Error Properties. Various levels of detail are returned with each. The content of each error type is detailed in the follow sections.

6.1 SOAP Exception

SOAP exceptions may be encountered for two broad reasons. One, if a SOAP message is malformed. Two, if the Web Service experiences some sort of general system failure. The SOAP Exception Scenarios section below provides examples for various error scenarios.

Any SOAP exception generated will conform to the SOAP 1.1 protocol. A SOAP exception will contain the following values (elements or attributes).

faultcode
  • String [var]
  • {Read} {minOccurs="1" maxOccurs="1"}
The faultcode will contain one of the following values:
  • VersionMismatch : The processing part found an invalid namespace for the SOAP Envelope element.
  • Client : The Client class or errors indicate that the message was incorrectly formed or did not contain the appropriate information in order to succeed. It is a general indication that the message should not be resent without change.
  • Server : The Server class or errors indicate that the message could not be processed for reasons not directly attributable to the contents of the message itself but rather to the processing of the message. The message may succeed at a later point in time.

Client and Server are the most common values returned.

faultstring
  • String [var]
  • {Read} {minOccurs="1" maxOccurs="1"}
A system generated text description of the error.
faultactor
  • String [var]
  • {Read} {minOccurs="0" maxOccurs="1"}
The URL of the Web Service. This value is only returned under certain circumstances. The value is generally not returned if an error occurs before or during the deserializing of the SOAP message. The value is generally returned if an error occurs after deserializing the SOAP message.
detail
  • Element
  • {Read} {minOccurs="1" maxOccurs="1"}

The detail element is always returned. The detail element may or may not contain details of the error. If details of the error are returned, they will be contained in a child “error” element.

The “error” element is generally not returned if an error occurs before or during the deserializing of the SOAP message. The error element is generally returned if an error occurs after deserializing the SOAP message.

And example of the detail element containing an error element is as follows:

If an “error” element is returned, it will contain the attributes “number”, “description” and “xmlns”. The possible values of the “number” and “description” attributes are described in Transaction Processing API Error Numbers and Descriptions.

6.2 SOAP Exception Scenarios

In example 6.1, a SOAP Exception is shown for a malformed incoming SOAP request. This type or error message format generally occurs when an error is encountered before or during deserialization of an incoming SOAP message. This type of error requires the request to be modified before being sent again.

Example 6.1 SOAP Exception for a Malformed Incoming SOAP Message

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <soap:Fault>
      <faultcode>soap:Client</faultcode>
      <faultstring>Server was unable to read request. --&gt; There is an   
      error in XML document (1, 406). --&gt; &amp;lt;SendAndCommit
      xmlns='http://api.e-xact.com/vplug-in/transaction/rpc-
      enc/'&amp;gt; was not expected.</faultstring>
      <detail />
    </soap:Fault>
  </soap:Body>
</soap:Envelope>

In example 6.2, a SOAP Exception is shown for an incoming SOAP request containing a null Transaction struct. This message format generally occurs when an error is encountered after deserialization of an incoming SOAP message. This type of error requires the request to be modified before being sent again.

Example 6.2 SOAP Exception for an Incoming SOAP Message Containing a Null Transaction

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <soap:Fault>
      <faultcode>soap:Client</faultcode>
      <faultstring>System.Web.Services.Protocols.SoapException: Setup Error at
      rpc-enc.Service.SendAndCommit(Transaction Transaction) in C:\Documents
      and Settings\defaultuser\VSWebCache\ secure.e-xact.com\vplug-
      in\transaction\rpc-enc\Service.asmx.vb:line 98</faultstring>
      <faultactor>http://api.e-xact.com/vplug-in/transaction/rpc-
      enc/Service.asmx</faultactor>
      <detail>
        <error number="400" description="Bad Request. Object reference not set
        to an instance of a Transaction object." xmlns="http://api.e-
        xact.com/vplug-in/transaction/rpc-enc" />
      </detail>
    </soap:Fault>
  </soap:Body>
</soap:Envelope>

In example 6.3, a SOAP Exception is shown for a general system failure. This message format generally occurs when an error is encountered after deserializing a SOAP message. This type of error usually results from an internal problem within the Web Service. The same request may work if sent at a later time.

Example 6.3 SOAP Exception for a General System Failure Within the Web Service

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <soap:Fault>
      <faultcode>soap:Server</faultcode>
      <faultstring>System.Web.Services.Protocols.SoapException: Setup Error at
      rpc-enc.Service.SendAndCommit(Transaction Transaction) in C:\Documents
      and Settings\defaultuser\VSWebCache\api.e-xact.com\vplug-
      in\transaction\rpc-enc\Service.asmx.vb:line 99</faultstring>
      <faultactor>http://api.e-xact.com/vplug-in/transaction/rpc-
      enc/Service.asmx</faultactor>
      <detail>
        <error number="500" description="Internal Server Error. An unknown    
        error occurred." xmlns="http://api.e-xact.com/vplug-  
        in/transaction/rpc-enc" />
      </detail>
    </soap:Fault>
  </soap:Body>
</soap:Envelope>

6.3 Response - Error Properties

If an incoming message is successfully received but the transaction not successfully processed, various error indicator properties are returned in the response. The properties may define three broad types of failure.

One, the error properties may indicate that invalid values were sent in the request. Two, the error properties may indicate that some sort of failure occurred while processing the transaction. Three, the error properties may indicate that the transaction was processed normally but still declined. (This is in fact not an actual error. It is described here, as the Merchant’s system may want to treat normal declines as a type of failure.)

An occurrence of the first error type is reflected in the following property values being returned:

Error_Number error number
Error_Description error description
Transaction_Error "False"
Transaction_Approved "False"

The error number and error description values that may be returned are defined in Transaction Processing API Error Numbers and Descriptions.

An occurrence of the second error type is reflected in the following property values being returned:

Error_Number "0"
Error_Description null
Transaction_Error "True"
Transaction_Approved "False"
Exact_Resp_code error code
Exact_Message error message

The error code and error message values that may be returned are defined in E-xact Response Codes (ETG Codes).

An occurrence of the third error type is reflected in the following property values being returned:

Error_Number "0"
Error_Description null
Transaction_Error "False"
Transaction_Approved "False"
Exact_Resp_code "00"
Exact_Message "Transaction Normal"
Bank_Resp_code bank response code
Bank_Message bank response message
Bank_Resp_code_2 bank response code 2 (usually null)

The bank response code and bank response message values that may be returned are defined in the article Bank Processor Codes (FI Codes). This type of failure is in fact a ‘normal’ decline. It is not a actual error. The Merchant’s system may want to treat declines as a type of failure.

Appendix 1. More About Service URLs

The Transaction Processing API has lived through a few iterations, consequently it may be known by different names and service URLs. 

Some of the names you might encounter in older documents:

  • Web Service
  • Payment Web Service Plug-In
  • SOAP fields/parameters (meaning API Request / Response properties)

Below is a comprehensive list of the service URLs:

Current (points to Version 8)
  • Endpoint
    • https://api.e-xact.com/transaction
  • WSDL
    • https://api.e-xact.com/transaction/wsdl
    • https://api.e-xact.com/transaction/service.wsdl

Version 8

 

  • Endpoint
    • https://api.e-xact.com/transaction/v8
    • https://api.e-xact.com/vplug-in/transaction/rpc-enc/service.asmx (legacy)
  • WSDL
    • https://api.e-xact.com/transaction/v8/wsdl
    • https://api.e-xact.com/transaction/v8/service.wsdl
    • https://api.e-xact.com/vplug-in/transaction/rpc-enc/service.asmx?wsdl (legacy)

Version 7

  • Endpoint
    • https://api.e-xact.com/transaction/v7
    • https://api.e-xact.com/vpos/process/vpos.asmx (legacy)
  • WSDL
    • https://api.e-xact.com/transaction/v7/wsdl
    • https://api.e-xact.com/transaction/v7/service.wsdl
    • https://api.e-xact.com/vpos/process/vpos.asmx?wsdl (legacy)
Have more questions? Submit a request

0 Comments

Please sign in to leave a comment.
Powered by Zendesk