Transaction Processing API Reference Guide

Created by Richard Moore, Modified on Fri, 1 Mar at 5:52 PM by Anna Byazina



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



JSON format

API request example:


curl -u 'ExactID:Password' \
   -H 'Content-Type: application/json; charset=UTF-8' \
   -H 'Accept: application/json' \
   -d '{
"transaction_type":"01",
"cc_number":"4111111111111111",
"cardholder_name":"Arthur Digby",
"cc_expiry":"0925",
"amount":"10.25"
}' \

https://api.e-xact.com/transaction


 


API response example:


{
 logon_message: null,
 error_number: 0,
 error_description: ' ',
 transaction_error: 0,
 transaction_approved: 1,
 exact_resp_code: '00',
 exact_message: 'Transaction Normal',
 bank_resp_code: '000',
 bank_message: 'Approved',
 bank_resp_code_2: null,
 sequence_no: '000004',
 avs: '',
 cvv2: null,
 retrieval_ref_no: '8495388',
 cavv_response: null,
 merchant_name: 'E-xact Transactions DEMO0106 USD',
 merchant_address: '1234 Demo Street',
 merchant_city: 'Tampa',
 merchant_province: 'Florida',
 merchant_country: 'United States',
 merchant_postal: '33600',
  merchant_url: null,

 ctr: '=========== TRANSACTION RECORD ==========\n' +
   'E-xact Transactions DEMO0106\n' +
   '1234 Demo Street\n' +
   'Tampa, FL 33600\n' +
   'United States\n' +
   '\n' +
   '\n' +
   'TYPE: Pre-Authorization\n' +
   '\n' +
   'ACCT: Visa  $ 10.25 USD\n' +
   '\n' +
   'CARD NUMBER : ############1111\n' +
   'DATE/TIME   : 04 Dec 20 20:27:35\n' +
   'REFERENCE # : 001 000004 M\n' +
   'AUTHOR. #   : ET184355\n' +
   'TRANS. REF. : \n' +
   '\n' +
   '    Approved - Thank You 000\n' +
   '\n' +
   '\n' +
   'Please retain this copy for your records.\n' +
   '\n' +
   'Cardholder will pay above amount to card\n' +
   'issuer pursuant to cardholder agreement.\n' +
    '=========================================',

 exact_issname: null,
 exact_issconf: null,
 gateway_id: 'AE5174-01',
 password: null,
 transaction_type: '01',
 amount: 10.25,
 surcharge_amount: null,
 cc_number: '############1111',
 transaction_tag: 2150127336,
 track1: null,
 track2: null,
 pan: null,
 authorization_num: 'ET184355',
 cc_expiry: '0925',
 cardholder_name: 'Arthur Digby',
 cc_verification_str1: null,
 cc_verification_str2: null,
 cvd_presence_ind: 0,
 zip_code: null,
 tax1_amount: null,
 tax1_number: null,
 tax2_amount: null,
 tax2_number: null,
 secure_auth_required: null,
 secure_auth_result: null,
 ecommerce_flag: 0,
 xid: null,
 cavv: null,
 cavv_algorithm: null,
 reference_no: null,
 customer_ref: null,
 reference_3: null,
 language: null,
 client_ip: '0.0.0.0',
 client_email: null,
 user_name: null
}


 



SOAP format

API request example:


curl -u 'ExactID:Password' \
  -H 'SOAPAction: http://secure2.e-xact.com/vplug-in/transaction/rpc-enc/SendAndCommit' \
  -H 'Content-Type: application/soap+xml; charset=UTF-8 \
-H ‘Accept: application/soap+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




API response example:


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: application/soap+xml; charset=utf-8
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
ETag: "d358d5fd6360a736466600964195fcc6"
Cache-Control: private, max-age=0, must-revalidate
Content-Length: 4591
Status: 200
Content-Type: application/soap+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"}



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_NumberTable 1.1
Transaction_Tag (Defines a tag which references a stored credit card number)Table 1.2
Track1Table 1.3
Track2Table 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.


C:\Users\CARA-USER\AppData\Local\Microsoft\Windows\INetCache\Content.MSO\F23EFBA2.tmp



C:\Users\CARA-USER\AppData\Local\Microsoft\Windows\INetCache\Content.MSO\F847533B.tmp


C:\Users\CARA-USER\AppData\Local\Microsoft\Windows\INetCache\Content.MSO\278BBC00.tmp

 C:\Users\CARA-USER\AppData\Local\Microsoft\Windows\INetCache\Content.MSO\B008C01.tmp


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

** Not supported for TSYS
*** Only Moneris supports this 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
  • String
  • {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, or 1. Note that null defaults to 0.

  • Null or 0 = Not Supported (Default)
  • 1 = Value provided by Cardholder

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.


3.1 Stored Credentials (AKA Credentials on File)




The purpose of this feature is to identify the card on file/stored credentials transaction type. The feature is presently supported for Mastercard and will be also supported for Visa, Discover, and Amex.

If the Stored Credentials fields are submitted they must be populated with valid values. Otherwise, the transaction may be rejected or processed as a regular credit card transaction.


Please note: If the transaction is approved, but the fields for Stored Credentials are not returned back in the API response, then the transaction has not been processed using Stored Credentials.

Please refer to the table below for the list of allowed values
(This table is applicable for Visa, Mastercard, and Discover. See the separate section for American Express)





Field Name JSON (XML/SOAP)



Allowed Values and Comments



stored_credentials


(StoredCredentials)



A nesting object. The API fields of Stored Credentials are nested under this object



indicator
(Indicator)



For Visa and Discover:
"1" - First time transaction
"S" - Subsequent transaction


For Mastercard: merchants should send "S" in the Stored Credential Indicator. Merchants do not need to separately identify first and subsequent transactions.



initiation


(Initiation)



"M" = Merchant Initiated


"C" = Cardholder Initiated



schedule


(Schedule)



"U" = Unscheduled


"S" = Scheduled



authorization_type_override
(AuthorizationTypeOverride)



For Visa only

"R" = Reauthorization of Prior Amount
"A" = Resubmission
"E" = Estimated Authorization
Space = Default

Note: Provide these values only if you want to explicitly mention the above scenarios.



transaction_id
(TransactionId)



Used only for Visa and Discover



An identifier, assigned by a card brand, used to uniquely identify and link all related messages and records used to authorize and settle the transaction through the card brand.

If a Merchant requires to receive the original transaction ID, then it needs to provide this record with the value equals “new” in the original authorization request. The “transaction_id” field will be returned in the API response with the ID if the transaction was approved.

If an original transaction ID was created, then in the follow-up transaction the ID must be submitted.  (e.g., for a recurring transaction).



original_amount
(OriginalAmount)



Used only for Discover

Approved amount in the original authorization.


"original_amount" is returned via the API response and must be used in the subsequent transactions. Without it a subsequent transaction may be rejected.


  


 


Stored Credentials for American Express


The usage of Stored Credentials for American Express is different from other card brands. For American Express the e-commerce flag defines if the transaction is Stored Credentials type or not. “stored_credentials” field shouldn’t be used for American Express transactions.

E-commerce flag is an API field: “ecommerce_flag” (JSON) and “Ecommerce_Flag” (SOAP/XML)



Available “ecommerce_flag” values for AMEX Stored Credentials 



Details



Send “ecommerce_flag”:”2”  for payments scheduled at regular frequency



Used for regular recurring transactions, such as periodic billings. The billing amount can vary but the frequency is scheduled.
Appropriate for membership dues, subscribed services, insurance premiums, wireless services, newspaper and other regularly scheduled charges.



Send “ecommerce_flag”:”X” for Re-authorize Transactions. 



Designates a non-recurring re-authorize scenario e.g., standing approval, card on file, or split shipment transaction.
This value should also be used to denote an American Express Payment Token transaction where cryptogram data is NOT available.
Used for situations where the cardholder information is on file, however, the billing frequency and amount are variable.
This value is appropriate for travel, car rental, lodging, delayed shipments, and split bill/subsequent Authorization transactions.



 


 


Sample API request in JSON format (Visa card)


 


{


 "cc_number": "4111111111111111",


 "cc_expiry": "0423",


 "cardholder_name": "Simon Jones",


 "gateway_id": "AD0123-01",


 "password": "sample_password",


 "transaction_type": "00",


 "amount": 12,


 "stored_credentials": {


   "indicator": "1",
   "initiation": "M",   
"schedule": "S",
   "transaction_id”: ”new”


 }


}


 


Sample Response in JSON format (Visa card)


 


{
"transaction_error": 0,
"transaction_approved": 1,
"exact_resp_code": "00",
"exact_message": "Transaction Normal",
"bank_resp_code": "100",
"bank_message": "Approved",
"sequence_no": "Replaced sequence_no",
"cvv2": "Replaced cvv2",
"retrieval_ref_no": "Replaced retrieval_ref_no",
"merchant_name": "Settlement - API Testing (Generic) 001",
"merchant_address": "1 API CAD Terminal Way",
"merchant_city": "Toronto",
"merchant_province": "Ontario",
"merchant_country": "Canada",
"merchant_postal": "M4B 1B3",
"merchant_url": "Replaced merchant_url",
"ctr": "========== TRANSACTION RECORD ==========\nSettlement - API Testing (Generic) 001\n1 API CAD Terminal Way\nToronto, ON M4B 1B3\nCanada\n\n\nTYPE: Purchase\n\nACCT: Visa $ 12.00 USD\n\nCARDHOLDER NAME : Simon Jones\nCARD NUMBER : ############1111\nDate/Time : REPLACED_DATE_TIME\nREFERENCE : REPLACED_REFERENCE_NNOO\nAUTHOR. : REPLACED_AUTHORICE_NNOO\nTRANS. REF. : REPLACED_TRANS. REF.\n\n Approved - Thank You 100\n\n\nPlease retain this copy for your records.\n\nCardholder will pay above amount to\ncard issuer pursuant to cardholder\nagreement.\n========================================",
"gateway_id": "Replaced gateway_id",
"transaction_type": "00",
"amount": 12.0,
"cc_number": "############1111",
"transaction_tag": "Replaced transaction_tag",
"authorization_num": "Replaced authorization_num",
"cc_expiry": "Replaced cc_expiry",
"cardholder_name": "Simon Jones",
"cvd_presence_ind": 0,
"currency_code": "USD",
"partial_redemption": 0,
"credit_card_type": "Visa",
"stored_credentials": {
"indicator": "1",
"initiation": "M",
"schedule": "S",
“transaction_id”: ”098765432154321”
 },

"cavv_response": "Replaced cavv_response",
"client_ip": "Replaced client_ip",
"bank_resp_code_2": "Replaced bank_resp_code_2",
"reference_no": "Replaced reference_no"
}


 


Sample API request in JSON format (American Express card)
example of a recurring transaction


{


 "cc_number": "340000000000009",


 "cc_expiry": "0923",


 "cardholder_name": "Simon Jones",


"ecommerce_flag": "2",


 "gateway_id": "AB0123-01",


 "password": "sample_password",


 "transaction_type": "00",


 "amount": "20.00",


 


}


 


Sample Response in JSON format (American Express card)


{"transaction_error":0,"transaction_approved":1,"exact_resp_code":"00","exact_message":"Transaction Normal","bank_resp_code":"100","bank_message":"Approved","sequence_no":"0619824","retrieval_ref_no":"190715","merchant_name":"some name","merchant_address":"675 main st.","merchant_city":"los angelese","merchant_province":"California","merchant_country":"United States","merchant_postal":"87664","merchant_url":"https://XXXXXXX.com","ctr":"========== TRANSACTION RECORD ==========\\njhgkjh\\n675 main st.\\nlos angelese, CA 87664\\nUnited States\\nhttps://XXXXXXX.com\\n\\nTYPE: Purchase\\n\\nACCT: American Express       $ 20.00 USD\\n\\nCARDHOLDER NAME :Simon Jones\\nCARD NUMBER     : ###########0009\\nDATE/TIME       : 15 Jul 19 17:44:21\\nREFERENCE #     : 002 0619824 M\\nAUTHOR. #       : 200316\\nTRANS. REF.     : \\n\\n    Approved - Thank You 100\\n\\n\\nPlease retain this copy for your records.\\n\\nCardholder will pay above amount to\\ncard issuer pursuant to cardholder\\nagreement.\\n========================================","gateway_id":"AB0123-01",
"transaction_type":"00","amount":20.0,"cc_number":"###########0009","transaction_tag":4301233334,"authorization_num":"200316","cc_expiry":"0923","cardholder_name":"Simon Jones",
"cvd_presence_ind":0,"ecommerce_flag":"2","currency_code":"USD","partial_redemption":0,"credit_card_type":"American Express"}


 



3.2 Digital Wallets (Apple Pay and Google Pay)*


*Apple Pay and Google Pay are only available for merchants using Chase Paymentech as their processor.


API version 10 or higher. Endpoint: https://api.e-xact.com/transaction/v10


If a digital wallet was used during a transaction, then  the following fields must be populated: 


  • wallet_provider_id
  • cavv
  • ecommerce_flag 




Field name



Data Type



Request Values



wallet_provider_id (JSON)


WalletProviderID (XML/SOAP)



String


(mandatory for digital wallets)



"4" - Apple Pay
"6" - Google Pay
"1"- default when not populated



cavv (JSON)
CAVV (XML/SOAP)



String
(mandatory for digital wallets)



Forward the cavv string that is returned from the wallet provider; do not modify the string.



ecommerce_flag (JSON)
Ecommerce_Flag (XML/SOAP)



String
(mandatory for digital wallets)



Forward the ecommerce_flag value that is returned from the wallet provider; do not modify the value.




API Request example (JSON)


{


"gateway_id": "XXXXXX-XX",
"password": "XXXXXXXXXXXX",
"wallet_provider_id": "4",
"cavv" : "XXXXXXXXXXXXXXXXX",
"ecommerce_flag" : "5",

"transaction_type": "00",
"amount": "10",
"cc_number": "XXXXXXXXXXXXXXX",
"cardholder_name": "Neil Mellor",
"cc_expiry": "0926"


}


 


API Response example (JSON)


{"transaction_error":0,


"Transaction_approved":1,


"exact_resp_code":"00",


"exact_message":"Transaction Normal",


"bank_resp_code":"200",


"bank_message":"Approved",


"sequence_no":"0226916",


"retrieval_ref_no":"170124",


"merchant_name":"Beaver Creek Water Co.",


"merchant_address":"12345 Main St",


"merchant_city":"East Liverpool",


"merchant_province":"Ohio",


"merchant_country":"United States",


"merchant_postal":"43920",


"ctr":"========== TRANSACTION RECORD ==========\nBeaver Creek Water Co.\n12345 Main St\nEast Liverpool, OH 43290\nUnited States\n\n\nTYPE: Purchase\n\nACCT: American Express $ 10.00 USD\n\nCARDHOLDER NAME :Neil Mellor\nCARD NUMBER : ###########1004\nDATE/TIME : 24 Jan 21 19:43:37\nREFERENCE # : 001 0226916 M\nAUTHOR. # : 989484\nTRANS. REF. : \n\n Approved - Thank You 200\n\n\nPlease retain this copy for your records.\n\nCardholder will pay above amount to\ncard issuer pursuant to cardholder\nagreement.\n========================================",


"gateway_id”:”XXXXXX-01",


"transaction_type":"00",


"amount":10.0,


"cc_number":"###########1004",


"transaction_tag":6579819,


"authorization_num":"989484",


"cc_expiry":"0926",


"cardholder_name":"Neil Mellor",


"cvd_presence_ind":0,


"currency_code":"USD",


"partial_redemption":0,


"credit_card_type":"American Express"
}


 


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.




PropertyDescription
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
  • String
  • {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_Numbererror number
Error_Descriptionerror 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_Descriptionnull
Transaction_Error"True"
Transaction_Approved"False"
Exact_Resp_codeerror code
Exact_Messageerror 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_Descriptionnull
Transaction_Error"False"
Transaction_Approved"False"
Exact_Resp_code"00"
Exact_Message"Transaction Normal"
Bank_Resp_codebank response code
Bank_Messagebank response message
Bank_Resp_code_2bank 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)


Was this article helpful?

That’s Great!

Thank you for your feedback

Sorry! We couldn't be helpful

Thank you for your feedback

Let us know how can we improve this article!

Select at least one of the reasons
CAPTCHA verification is required.

Feedback sent

We appreciate your effort and will try to fix the article