Credit Card Form Interface
The Credit Card Interface consists of a single request and a single response. Each is described below.
1. Request
You must pass a request to the the ePay CGI as if the browser were passing a completed form. The 'post' method is used. Below is the definition of each form field expected. Below the definitions is an actual example. Replacing the form variable values in the example will give you a working example. When your program generates the same outputs as the modified example, the request portion is complete and should work.
| Variable | Type | Value | Notes |
|---|---|---|---|
| (*1) | |||
| formid | C | webx001a | Tells the system which authentication system to use. Do not change this value unless instructed. |
| formver | C | 01.01.01 | Certain forms can change their actions based on the form version. |
| formcmddata | C | This constant tells the system that you are using an external interface. Without this constant, the system will prefill the browser window but will not submit the transaction automatically. You can have transactions submitted automatically by using "forcecc" (without the double-quotes) as the value. | |
| client | A | (CLIENTID) | Each client is assigned an ID. You will use your unique client code here. Client IDs are always upper-case. |
| user | C | anon-cc | Use the anonymous ACH account, which requires no special configuration of the ePay system. If doing shared authentication, this value will be the operator ID of the person submitting the transaction. True authentication requires special configuration. |
| password | C | nopassword | The anonymous ACH account always uses this password. |
| action | C | LogIn | Tells the system to complete authentication prior to processing the ach variables. |
| clcode | R/O (*5) | Optional client identifier, limited to 32 characters. When used for a third party, this can be an ID to uniquely identify the third party in your system. | |
| clname | R/O (*5) | Optional client name (would match clcode in your system), limited to 64 characters. | |
| cid1 | R | The account number used by the remote system to identify this payor. This ID is returned in the payment interfaces and is required. It is limited to 32 characters. | |
| cid2 | R/O (*5) | Alternate ID number. This ID may be returned if you have a custom payment interface. It is limited to 32-characters and is generally optional. | |
| ccompany | R(O) | Company. When taking payments on behalf of a third party, this should be the third-party's name. This will help a payor identify the ultimate recipient of the payment. Some clients may elect to make company optional. The interface follows the same requirements of the on-line system. If in doubt, consult your on-line payment form or contact support. | |
| cname | R | Payor name, limited to 40 characters | |
| caddr1 | R | Payor address line, limited to 40 characters | |
| ccity | R | Payor city, limited to 25 characters | |
| cstate | R | Payor state, limited to 2 characters. For international addresses (outside North America), use 'XX' for state. | |
| czip | R | Payor zip code, limited to 5 digits. Use '00000' if state code is 'XX' | |
| cphone | R | Payor phone number, limited to 25 characters. The phone number can be formatted (e.g., 412/788-3900, 412.788.9000) or just consecutive digits (e.g., 4127883900). | |
| cemail | R | Payor's email address, limited to 64 characters. Must be a properly formatted email address. The receipt for the transaction is sent to this address. If no payor email is available, you must use a "catch-all" account on your own email system (e.g., ccreceipts@yourdomain.com). | |
| chname | R | (*2) | |
| chaddr1 | R | (*2) | |
| chcity | R | (*2) | |
| chstate | R | (*2) | |
| chzip | R | (*2) | |
| chphone | R | (*2) | |
| chemail | R | (*2) | |
| cardtype | R | Card Type -- two character value. 01=Visa, 02=MasterCard, 03=Discover, 04=Amex | |
| cardtypex | R | Card Type -- text. Visa, MasterCard, Discover, Amex (should match cardtype) | |
| cardno | R | Credit Card number | |
| expmo | R | Credit card expiration month. 2 digit month, right-justified, zero-filled | |
| expyr | R | Credit card expiration year. 4 digit year. | |
| cvv2 | R | Credit card verification code. | |
| amount | R | Dollar amount of the transaction. The format is left justified, optional zero-filled, single decimal point, two decimal digits. An integer-only value is permitted. Examples are: 1.00, 1, 0001.00. No special characters such as dollar signs, commas or signs are permitted. (*4) | |
| pgroup | C/A | 0 | The value should be '0' unless you are doing multiple payment groups. If you have established payment groups, contact support to get the list of valid values. |
| certify | C | 1 | Each client designs the wording of the contract in the on-line system. It is assumed that you are abiding by that contract through the interface. A value of '1' indicates that you certify all the information true and accurate. |
| payforx | O | This is a "Payment for" line. Additional information about the transaction can be recorded here, limited to 64 characters. | |
| payfor | O | Payfor is always a '0' or a value provied by us from the drop down list. |
Notes:
- (*1) C=Constant, R=Required Variable, O=optional variable, A=Assigned by EBS (contact your support rep)
- (*2) All account holder fields match the definition of the payor fields. If the account holder is different than the payor, you are strongly encouraged to capture and present the actual account holder's information. If the account holder is the same as the payor, please duplicate the payor values into the account holder variables.
- (*3) The "payon" date is the date you would like the transaction to be processed. If all parts of the date are blank or zeroes, the current date is used. Payments scheduled for the current date after the client's established cut-off time will be scheduled for tomorrow. Payments scheduled in the past will not be accepted. Client's can limit how far in the future payments are accepted. If the payon date exceeds that limit, the payment will not be accepted.
- (*4) Be aware that the actual amount of the transaction may be different than the amount requested. The ePay system will calculate the true amount of the transaction by adding the fees on top of the amount requested.
- (*5) These fields are not required by the payment system. Each client has the option to have them required for their record keeping or other reasons (e.g., payment interfaces). If these fields are required in the on-line system, they must be provided in the remote interface. If they are optional in the on-line system, you can provide them but they are not required.
Additional Comments:
- All variable names are case-sensitive
- All constants and assigned variables are case-sensitive and must be provided as shown. All other variables are not case-sensitive unless noted in the table above.
Sample Form:
<!DOCTYPE HTML PUBLIC "-//W3C/DTD HTML 3.2//EN">
<html>
<head>
<meta HTTP-EQUIV="Pragma" CONTENT="no-cache">
<meta HTTP-EQUIV="Cache-Control" CONTENT="no-cache">
<title>ECSI Login</title>
</head>
<body onload="document.form01.submit()">
<form name="form01" method=POST action="https://www.ecsi.net/cgi-bin/webt.exe">
<input type="hidden" name="formid" value="webx001a">
<input type="hidden" name="formver" value="01.01.01">
<input type="hidden" name="formcmddata" value="">
<input type="hidden" name="client" value="DEMO-EPAY">
<input type="hidden" name="user" value="anon-acpay">
<input type="hidden" name="password" value="nopassword">
<input type="hidden" name="action" value="LogIn">
<input type="hidden" name="cid1" value="111111111">
<input type="hidden" name="cid2" value="">
<input type="hidden" name="ccompany" value="ECSI">
<input type="hidden" name="cname" value="John Smith">
<input type="hidden" name="caddr1" value="181 Montour Run Rd">
<input type="hidden" name="ccity" value="Coraopolis">
<input type="hidden" name="cstate" value="PA">
<input type="hidden" name="czip" value="15108">
<input type="hidden" name="cphone" value="4127883900">
<input type="hidden" name="cemail" value="rleech@ebillsvc.com">
<input type="hidden" name="chname" value="John Smith">
<input type="hidden" name="chaddr1" value="181 Montour Run Rd">
<input type="hidden" name="chcity" value="Coraopolis">
<input type="hidden" name="chstate" value="PA">
<input type="hidden" name="chzip" value="15108">
<input type="hidden" name="chphone" value="4127883900">
<input type="hidden" name="chemail" value="rleech@ebillsvc.com">
<input type="hidden" name="cardtype" value="01">
<input type="hidden" name="cardtypex" value="Visa">
<input type="hidden" name="cardno" value="1111111111111">
<input type="hidden" name="expmo" value="08">
<input type="hidden" name="expyr" value="12">
<input type="hidden" name="cvv2" value="1111">
<input type="hidden" name="amount" value="1.00">
<input type="hidden" name="pgroup" value="0">
<input type="hidden" name="certify" value="1">
<input type="hidden" name="payforx" value="">
<input type="hidden" name="payfor" value="0">
</form>
</body>
</html>
2. Response
Most external applications will post some number of form fields and allow the user to complete data entry. There is no response page for this type of interface (e.g., the response is the entry form and it is presented to the user). If you have arranged to have your form automatically post, you will receive a special response buffer as described below.
The system will present a response page after a successful request. The page will have three, formatted HTML comment lines as shown below. You will need to search for the first line (it is not the first line of the response page). Once you find the first line, the three lines will appear in order.
Sample Response Lines
<!-- Response: text1-->
<!-- Reason: text2-->
<!-- Seqno: number-->
The definition of the response lines is as follows:
text1
If blank, it implies that your request did not pass the basic javascript validations on the form. Usually, a required field is missing. If not blank, it will contain either "Accepted" or "Rejected". A rejected transaction will not be recorded in the system and must be corrected and resubmitted if you wish to have it processed. An accepted transaction will be presented to the bank in the next processing run.
text2
Will contain a textual description if the transaction is rejected. This is a meaningful explanation such as "The Card Number is not valid."
number
If a transaction is accepted, this number will contain the ECSI/EBS assigned transaction number. You should record this number in your system for future reference. If there is an issue with a transaction, they can be identified immediately by the transaction number. Otherwise, a lengthy search may be required.
The rest of the Response Page can safely be ignored. As the ePay system is primarly an on-line system, it will contain other information which made up the page that would have been presented to the user.