Direct Mode is a direct interface to the Ezic payment gateway, designed to be used in situations where the standard Ezic Payment Form is not appropriate. It supports all the same functions, including check payment, Credit Card payment, membership signups, and automatic rebillings.
Using Direct Mode requires some knowledge of advanced CGI scripting or other programming techniques. Any examples given in this document will be provided in Perl. Additionally, a Perl script for Direct Mode access is available from Ezic, and may speed your development. A Java and C Direct Mode client is also available, contact Ezic support at 847-327-9870 for more information. Of course, developers are welcome to write their own client libraries based on this specification.
The basic transaction in Direct Mode works as follows: The merchant's system makes a standard HTTP connection to the Ezic server, passing the transaction data in an HTTP POST operation (with the parameters encoded in the body of the request). The Ezic system then processes the transaction, and returns either a HTTP 200 (OK) along with the relevant return values, *or* the Ezic server will return an HTTP 400 (ERROR) and the body of the response will be set to a string indicating the reason for the error.
The URL for Direct Mode 2.1 is: https://secure.ezic.com/gw/native/direct2.1
See the appendices for specific fields to pass. Please contact Ezic for any additional information. E-mail support@ezic.com.
The most robust and secure way to issue a transaction via Ezic's Direct Mode is to first obtain a Transaction ID from the Ezic servers to assign to the transaction. Then if the transaction fails to return for any reason, it is still possible to track the transaction's status through the online reporting system.
To obtain a valid TransID (passing a made-up or invalid TransID can cause serious processing errors) you can query the following URL:
The ID to use for the next transaction will be returned in the body of the response. It is possible to request multiple IDs simultaneously; simply append a ?x to the query URL, where x is the number of IDs to request. All the IDs will be returned int he body of the response, separated by newlines.
Each ID is valid for ONE transaction only. The script must get a new ID for each new transaction.
If the transaction should fail to return a proper response code for any reason, the status of the transaction can be gotten by querying the following url:
Pass the Trans ID of the transaction to poll for in as a trans_id cgi parameter. The script will return the following values, cgi-encoded (or an error 400 if there is an error):
found = Y if found, N if not found. If found=N, it will be the only parameter returned.
status = Status code, same as RET_STATUS below (appendix B)
trans_id= The transaction ID you posted to the script
amount = Amount of the transaction
message = Human-readable status message
issue_date = Date the transaction was issued
cap_date = Date the transaction was captured
origin = Origin of transaction (V-Terminal, Direct Mode, etc)
It is possible to allow Ezic to handle membership signups for member-based websites. If this option is used, Ezic will store the user names and passwords along with the associated transaction data. The valid login names and passwords will be sent to a control CGI on the member-based website. A sample Perl CGI for accepting this data is available from Ezic.
The specifics of the CGI Membership postings are outside the scope of this document. Separate documentation for this feature is available from Ezic.
In the case of membership signups, it is possible to automatically rebill the customer's credit card or EZICheck account to renew the membership on a regular basis. Rebilling periods can be specified as either a number of days between rebillings (1, 7, 30, etc) or as an SQL-style date expression. If specified in an SQL-style expression, the initial membership period can also be prorated. For instance, if a website renews memberships on the first of each month, and a person signs up on the 15th, they will be billed for only half a normal membership.
Note that there are legalities involved with automatic rebilling. Following the laws is the responsibility of the merchant, not Ezic.
It's possible to remotely affect changes to rebilling information such as amount and period, as well as membership information such as expiration, login, and password. The full interface for this works similarly to Direct Mode and is documented in the membership update script documentation.
Crypto-Hash is Ezic's proprietary system for ensuring data integrity across insecure connections. While the connection to Direct Mode is typically made with a secure HTTP (https://) connection, additional security is always recommended, particularly for financial transactions.
When using Crypto-Hash, all the fields required for the transaction are passed just as normal to the Direct Mode interface. However, an MD5 checksum of the critical transaction data is also sent. If the data is compromised in transmission, Ezic's server will reject the transaction.
The MD5 checksum is determined in the following way: In the GEN_HASHFIELDS parameter, pass a SPACE-SEPERATED list of the field names to be included in the checksum. It is highly recommended you include at least the GEN_AMOUNT and ACH_* or CARD_* fields. For instance, the GEN_HASHFIELDS parameter may contain, 'GEN_AMOUNT CARD_NUMBER CARD_EXPIRE CARD_CVV2'.
The values of the fields you have chosen should be concatenated into a single string, with the Crypto-Hash Key (set on the Ezic server in your account config) prepended to it. To continue the example, if you Ezic Crypto-Hash key is 'lwdf37r4j8RrzdHm4gi5' then the string would be something like,
"lwdf37r4j8RrzdHm4gi525.00412312341234123402023456" | | | | | \Crypto-hash key \ \CC # \ \CVV2 \amount \exp
Take this string and hash it using MD5, then pass it to Direct Mode in the GEN_HASHVALUE_MD5 parameter. The parameters will be encoded on Ezic's end by the Direct Mode interface and compared to the value passed from your server. If they do not match, the transaction is rejected.
Of course, this is only secure so long as your Crypto-Hash key is secure. If you believe your crypto-hash key has been compromised, immediately generate anew one and update your scripts to reflect the new value.
Note that when using Crypto-Hash, at least TWO fields must be included, or the system will give you an error. Using less than two fields is not as secure, and not recommended.
This is the number of your Ezic merchant or agent account, as a 12-character string. Required for ALL transactions.
The site tag of your website configured in the Ezic system. Required for membership transactions, optional for others.
An optional description of the product or services paid for. Up to 4000 characters
The amount of the transaction. Optional for refunds/voids as it will be taken from the amount of the original transaction. Must be 0.00 for AVS-only.
Additional miscellaneous info to accompany the transaction, up to 4000 characters.
Indicates the type of the transaction:
'AVS' - Address verification only, no charges
'AUTH' - Pre-Auth a charge card for later capture
'CAPTURE'- Capture a Pre-Authed charge
'SALE' - Standard charge/check transaction
'CREDIT' - Credit the charge/check account instead of charging it
'REFUND' - Will attempt a VOID or a Refund of a previous 'SALE'
'NONE' - For doing a transaction that is only a member signup, no payment
'ABORT' - Will abort a pending capture
Single-character field. 'C' for Charge, 'K' for Checks
Used for additional security in a transaction. Optional but HIGHLY recommended. See the section above on Crypto-Hash for more details.
Optionally specify the Ezic Transaction ID for this transaction. Optional and rarely used; if the Transaction ID specified already exists, errors will occur.
An Ezic Transaction ID returned from a previous transaction. Used for 'REFUND' type transactions, the amount of the refund/Void and other relevant data will be taken from the original transaction data.
Set to 1 to temporarly disable Fraud Barricade for this particular transaction only.
The customer's IP address and host. This is used for fraud screening, but is optional.
These fields contain all the customer's billing data. They are optional, but needed to perform Address Verification, and often including them results in alower rate for the transaction.
Credit Card Account Number -- required for Credit Card transactions.
Credit Card expiration date, in MMYY format
Credit Card CVV2 value. This is the three or four digit code on the back of the customer's credit card. Optional, but often will get a lower rateon the transaction
Force code provided by credit card processor. Optional.
Checking account routing code. Required for check transactions.
Checking account number. Required for check transactions.
An optional check sequence number, provided by the customer.
The above three fields are optional, but necessary for proper fraud screening. In any case, only ONE of the above fields will be used if provided, in this order of preference: SSN, then DL, then TAXID.
The two-character postal code for the state the ID was issued in. Leave blank if inappropriate, for instance, when using SSN.
Set to 1 for membership transactions, 0 or null for non-membership.
Required for membership signups. Specifies how long the membership is valid for.
The member's login name. The transaction will return an error if this name is already in use
The member's password.
An optional memo text field to associate with the member, and display on the edit member screen within the system
Set to 1 to start rebillings on this transaction, 0 or null for not.
The number of rebillings to perform, required for rebillings.
The length of time between rebillings, specified in days, or an SQL date expression.
The amount to charge the customer's card/check account for each rebilling.
Optional, if you use a SQL date expression for rebillings, the amount of the initial period can be prorated if a '1' is passed in this field.
The definitive status of the transaction. Single-character field:
1 = Successful
0 = Failed
F = Failed
R = Returned/Voided (will not occur in this context)
T = Successful Auth-Only
I = Incomplete, but successful. This is returned from check transactions that are successful, but may still fail at a later date due to NSF. Should be responded to exactly the same as a '1'.
Any other returned codes should be interpreted as success for future compatibility.
Human-readable message describing the state of the transaction, or the reason for failure
Ezic's Transaction ID for this transaction
VISA/MC Transaction ID
Address Verification response -- only for charge transactions
Human readable AVS response -- only for charge transactions
The issuer of the Credit Card, for charge transactions only.
CVV2 Verification code
Human readable CVV2 response
The Direct Mode does support multi-threading. Multiple transactions can be sent to the Direct Mode simultaneously, and each will be resolved independently.
If you take advantage of Direct Mode multi-threading, you must take into account the speed at which your processor can process transactions. You must insure that you do not send transactions faster than they can be processed by your processor (FDR, VITAL, NOVA, etc.).
FDR-OMAHA only allows one transaction per merchant account at a time.
Even though the Ezic Direct Mode supports multi-threading, FDR-OMAMA does not.
Therefore, when preparing a Direct Mode script for FDR-OMAHA, scripters should single thread, waiting for a response before sending the next transaction.
Sending transactions multi-threaded on FDR-OMAHA can result in slower than usual transaction responses and transaction loss at batch close time. Since the batches on OMAHA cannot exceed 500 transactions, this could mean a loss of a handful of transactions in every 500 sent.