Developer Implementation Guide
E-xact Developer Implementation Guide
Click and scroll to view topics regarding Developer Implementation:
- Connectivity of Components
- Once Registered with E-xact
- E-xact Payment System
- Transactional References
The E-xact Developer Implementation Guide is intended to outline the basic services and functionality of E-xact’s transactional processing services gateway and software.
Installation Instructions - For installation instructions for the various E-xact’s APIs please refer to the Read Me file and various help files found in the API version package you are implementing.
Connectivity of Components
The E-xact remote component connects to the transaction-processing network via a standard IP socket connection. All data passing through that connection is encrypted using a 448 bit private key.
The components connectivity point is managed through a Domain Name. Each component has two domain names (Primary, Secondary). If the component is unable to connect to the primary Domain, a connection to the Secondary domain is attempted.
The Domain Names and their IP addresses are stored on the local computer in a configuration file.
Once Registered with E-xact
E-xact Payment Gateway IDs
E-xact’s system uses a Payment Gateway ID and Gateway Password, to identify an individual’s E-xact payment gateway. The codes also establish the interaction between the E-xact software you integrated into your solution and our payment servers. The IDs you will receive consist of:
- Gateway ID (9 character identifier)
- Password (variable length).
As a developer there are a series of Payment Gateway IDs you will encounter:
- Test Acount IDs (for test environment)
- Individual Test Account IDs (optional, for test environment)
- E-xact Production ID (for production environment)
When you are ready to move from Test mode to Production mode (which means you are ready to send live transactions through to the banks), you will have to replace the Test Account ID with the E-xact Production ID. The E-xact Production ID is only set after the merchant customer has completed their registration with E-xact.
All developers who have registered E-xact’s APIs have access to E-xact’s test servers and testing account, ConnectionShop. This testing area is open to the general public. Upon registration of the component you are automatically assigned an E-xact Test Account ID.
With an E-xact Test Account, you can simulate the interaction between your software and/or server and E-xact’s servers. You can send test transactions through to our gateway and receive a response back from our network to verify that the transactions are being communicated properly between you and E-xact.
The sample scripts provided with E-xact’s software are always set with default values to connect to E-xact’s test servers. The test area is shared among developers. So your test transactions are pooled into a common account.
To view your test transactions, you will need to log into E-xact’s ConnectionShop within E-xact’s Realtime Payment Manager (RPM). You will have received a Test User Login ID and password provided with our software.
Individual Test Account (optional)
Developers can establish an individual test account for their software testing after you or the merchant business has registered for E-xact’s services. An individual Test Account is different from a regular test account in that you receive a separate viewing area that records only your test transactions. Also, if you plan to continue testing periodically, even after the merchant solution has launched, an individual test account is a safe way to test any changes you work into your solution. To set up an Individual Test Account, you will need to contact E-xact’s Technical Support.
Production IDs are passed along after the merchant has completed registering with E-xact. Once the Production IDs are entered into E-xact’s component software, the connection to E-xact’s servers and the bank networks has been established. Developers should test further to see that the Production environment is connecting properly.
Testing with credit cards within the production environment
If you decide to test the production environment with real credit cards, please use common sense. E-xact does not have test credit card numbers for production-level transactions. Here are some guidelines:
- Do not enter large dollar amounts. You will shortly exceed the credit limit on the card, and possibly block the cardholder’s card. We suggest you input small currency amounts such as a cent or a dollar so as to not exceed any credit limit on the card.
- Make sure to refund any purchases made with the card.
- Avoid repeated use of one card. It can alert banks of possible “mischievous activity” and could result in
the card being blocked.
- Don’t forge an expiration date or name. The bank may view this as “mischievous” conduct on the card.
Also note that pre-authorizations will only be charged to a cardholder if they are followed by a pre-authorization completion. The pre-authorization will remain for a few days on the cardholder’s card.
To view transactions in the Production Account, please refer to the information below.
RPM User Logins
Each E-xact customer receives User logins and passwords for E-xact’s RPM accessed on our website. Merchants can select User access as:
- Merchant - access to all screens
- Read Only – no access to POS and refund functions
- Developers should access this area to monitor production-level testing. Simply enter the User Login and password you have received from E-xact or your customer. Within this area you can view the transactional activity of the merchant customer.
Functions within RPM
A demonstration of RPM functions is available upon login.
Searching for a transaction
Under Transactions, transactions can be found by a variety of parameters including cardholder name, date, card type. You can view approved and declined transactions and read a transaction detail for each one sent to E-xact’s system. Please note only the last 4 digits of the credit card numbers are visible.
Conducting Refunds in RPM
Refunds can be conducted in Search by selecting the particular transaction record you would like to refund, or in POS screen. Please note there are rare exceptions to being able to refund via our Search or POS, due to bank restrictions or card restrictions (based on amount, cardholder policy, etc) or configuration restrictions set between the merchant and E-xact.
Making Changes to Users
Only administrators of the account can add new users. If you need to change your login and/or password, add a new user or remove a current user please contact E-xact Customer Service directly to request your changes.
E-xact Payment System
E-xact has the ability to support different currencies. The type of currency is defined by the merchant bank account. For each different currency type, E-xact establishes a separate Production ID. The various credit card accounts provided by the merchant are assigned to whichever currency gateway they fall under. Programming logic should be produced by the developer, which will distinguish between the separate currencies, and direct the appropriate E-xact production ID to the proper currency.
Cardholders are charged in whatever currency the merchant offers. Therefore multiple currencies does not apply to the processing of international cardholder credit cards. A foreign cardholder’s purchase is converted into their local currency and charged the daily exchange rates applied by the bank and credit card company.
Multiple Points-Of-Sale can be differentiated within a business by using multiple terminals. E-xact has the ability to set up multiple terminals under each currency. Each terminal receives a separate Gateway ID and Gateway password. Logic must be implemented by the developer to establish the appropriate Exact Production ID for each separate terminal.
Duplicate Checking (Optional)
All merchants are set up with default value Duplicate Status of Unrestricted. The currently supported Duplicate Checking types are:
E-xact will pass all transactions through to the bank without question. No Duplicate checking is done.
2. Deny All
All Duplicate transactions received with a given period of time are declined by E-xact and not sent through to the Bank
Duplicate transactions are defines as 2 or more transactions occurring in a specified period of time with the following fields exactly the same.
- Transaction Type
- Credit card Number
The time period is measured in minutes. At sign-up, the merchant has the option of activating duplicate transactions or not. The normal time period is 10 minutes.
If an incoming transaction is flagged as a duplicate, it is not passed on to the financial institution and is returned to the client with a “Transaction not Completed” status. A message indicating that it was duplicated is returned in the response.
Refund Checking (Optional)
As with Duplicate Checking, Refund Checking is specified by the merchant upon registration. All merchants are set-up with a defaulted Refund Status (or value) of Unrestricted. Most financial institutions place few limits on the number of refunds that a merchant may process or how those refunds match up to existing purchase transactions.
The currently supported E-xact Refund Checking types are:
E-xact will pass all transactions through to the bank without question. No Refund checking is done.
2. Refund Volume
On a daily basis, refund transactions are limited by the following criteria:
- Total Number of Refunds
- Total Dollar Amount of all Refunds
If either of or both of these limits are surpassed on a given day, all subsequent Refunds will not be
Reference No. (Optional)
Ref # is a user-defined transactional property that is returned unchanged once the transaction is completed. The information is entered in the Reference field under E-xact’s Search screen in RPM.
AVS – Address Verification System
Address verification is currently supported for customers with US or CAD based merchant accounts. Merchants who do not provide address information in their transactions may be subject to additional fees imposed by their acquiring institution or bank.
Address Verification String # is a number that is part of the AVS system. As a means of detecting fraudulent transactions, AVS matches the address sent with the transaction to the actual billing address of the cardholder. When address verification is requested, the field will contain the mailing address on the cardholder's monthly statement. This field cannot exceed 29 characters in length. The Address is provided in the “VerificationStr1” field and must be formatted as follows:
< street address >< apt no. >< zip code >
or < post office box number >< zip code >
If any of the address fields are not available or not applicable, they may be omitted. If available, the last 5 or 9 digits, without embedded spaces, should be the zip code. Numbers are not spelled out. (“First Street” becomes “1ST Street”, “Second” becomes “2ND”, etc) “Spaces” are only required between a numeral and the ZIP code.
1391 ELM STREET 40404
is equivalent to: 1391ELMSTREET40404
P.O. BOX 24356 55555
is not equivalent to: P.O.BOX2435655555
IMPORTANT: This information is provided to E-xact in property: VerificationStr1.
NOTE: if using Chase Paymentech or Moneris as your processor, please use the format outlined here.
Property: VerificationStr2 is to support future verification strings being deployed by Visa and other
credit card companies. (i.e. EVV2).
The AVS result is a one character response that indicates the “degree” of match for the provided
address. Currently supported AVS responses are:
North American Response Codes
AVS Message/AVS Code
Exact match, 9 digit zip / X
Exact match, 5 digit zip / Y
Address match only / A
9-digit zip match only / W
5-digit zip match only / Z
No address or zip match / N
Address unavailable / U
Non-U.S. Issuer does not participate / G
Issuer system unavailable / R
Not a mail/phone order / E
Service not supported / S
International Response Codes
AVS Message/AVS Code
Global non-AVS participant / G
Address matches only / B
Address and Postal Code do not match / C
Address and Postal Code match / D
Address and Postal Code match (UK only) / F
Address information not verified for international transaction / I
Address and Postal Code match / M
Postal Code matches only / P
The AVS result is independent of the authorization of the transaction. An AVS result of “N” may be returned with a valid authorization. The AVS result should be treated as an indicator of whether or not to accept the authorization that was provided.
A transaction with an AVS result that met the minimum criteria specified by the merchant would be committed, while a transaction that did not should be dropped.
if AVS in [“X”,”Y”,”A”] then CommitTransaction
Note: E-xact’s FormPost software cannot drop a transaction. See the Readme files for
Customer Transaction Record (CTR) Display
It is a requirement of most financial institutions that the CTR be displayed to the cardholder after all transactions. The format of E-xact’s CTR is fixed font plain text. If this format does not meet with the graphical requirements of your Web page, the CTR can be built using existing component properties. The CTR displays bank information, cardholder name, merchant name and address and status of the transaction (approved or declined).
SSL (Secure Socket Layer)
If you are using E-xact’s services for Web-based transactions, Secure Socket Layer for Web server with 40 or 128 bit encryption should be established. SSL appears as https:// in a Web browser. E-xact does not provide SSL certification. Digital Certificates can be obtained from Certificate Authorities. E-xact has no preference as to which SSL type or brand is used.
There are 6 properties that can be used to derive information about a transaction response. These responses are relevant after a call to the function CommitTransaction. Transaction_Approved will always return False and Transaction_Error will always return True before CommitTransaction is called.
Returns true if the transaction has been approved by the bank and there are no processing errors. It is possible for an authorization number to be present when Transaction_Approved is False. This occurs when an error occurs after the transaction has been approved by the bank. In these cases, the authorization is automatically reversed by the server. In most implementations, this is the only property that needs to be validated in your source code.
Indicates whether there were any errors while processing the transaction or that the transaction has not been fully completed.
Indicates the final status of the transaction. If there were no errors, this property should return “Transaction Normal”. When Transaction_Error returns true, “Exact_Message” should be examined for the cause of the error. Note: Exact_Message does not indicate whether or not the transaction was approved.
The code that accompanies the Exact_Message, for “Transaction Normal” the code is “00”. Please see the table below for a list of Exact Response Codes.
The Transaction message returned from the financial institution. This message is not modified by E-xact.
The code that accompanies the Bank_Message. The meaning of this code is dependant on the financial network that the transaction was processed through.