ExpertLink Introduction
ExpertLink is the programmatic connection tool IntelliPay business clients or ecommerce developers use to connect their web sites, shopping carts, store software, catalog systems, Internet appliances and back or front office systems to our real-time ePayment transaction processing system.
At the time of this writing, ExpertLink is composed of our LinkSmart product with many powerful extensions in the messaging protocols which deliver many new features to your remotely connected system.
ExpertLink gives you tremendous power and flexibility in your site design, ordering and payment processes, payment data capture and analysis, as well as access to a complete real-time data stream you can use to tie payment data into your other business systems. With ExpertLink you retain complete control over your business, web site, interface and processes, building IntelliPay products and services into your systems with transactions running “in the background” making IntelliPay invisible to your customers.
There are many possibilities in implementing IntelliPay. Later, there is a short list of example implementation possibilities.
Your Responsibility for Implementation
The responsibility for linking a web site using ExpertLink is with you or whoever is responsible for the web site in general. In most cases, ExpertLink implementation is simple and direct and should provide no problems for anyone with standard Internet programming.
If you are using a “shopping cart” or other program that already has IntelliPay v4 support integrated then you should have no IntelliPay-related programming to do.
This document provides the data necessary to link a web site IntelliPay, and in some cases some example, generic code snippets that may be helpful. It’s unlikely that these code snippets, as is, could be cut and pasted into your web site and have them work. Using ExpertLink, these tags (Name=Value pairs) must be sent via HTTPS (HTTP via SSL) with the programmed connector built by your staff. There are several publicly available tools for most programming languages that make this possible and relatively easy. Notably, the availability of the OpenSSL library makes SSL programming relatively painless and several tools exist for many languages making the sending and receiving of HTTP possible.
Additionally, IntelliPay provides various tools the ExpertLink user / developer can use to extend functionality from basic credit card processing to include AVS Controls, Duplicate Transaction controls and more. From time to time we will be releasing new features and tools and the ExpertLink protocols to use them. Developers and businesses should monitor our web site for these new capabilities in order to upgrade their implementations.
IntelliPay and its support staff cannot be, and are not, responsible for ensuring that your web site is programmed properly for use with ExpertLink or other products or services. Any custom programming needs of a specific web site are likewise beyond the scope of this document, IntelliPay and it’s staff. Also, while we know many web designers, web developers and others, we won’t make any specific recommendation to any single developer. We may be able to refer you to several for you to choose who you would like to use, but we can assume no responsibility for that developer’s work.
Who Should Use ExpertLink
Any business that is looking for a reliable, high-speed, secure real-time payment processing system to build into their own systems should use IntelliPay’s ExpertLink.
Primarily, ExpertLink is for merchants or developers who:
- Have a secure server and will be serving their own secure payment pages.
- Will build or write a program to securely connect to IntelliPay across the Internet to use our high-speed, two-way secure data streams for payment transactions. This program must use HTTP and SSL to connect successfully to IntelliPay.
First Steps and Implementation Decisions
Initially, you should read this entire document before attempting to implement anything you learn. There are several choices to make during configuration and installation and you should decide which tools and features to use, and what configurations to set. In general, your overall steps probably should look like this:
- Read this document, making notes for yourself of ideas or things to understand.
- Make your business and programming decisions about which IntelliPay products or services you will integrate. Will you use the Duplicate Transaction System? The AVS transaction control tools? The Batch Management tools? What business decisions will you need to make? Besides the normal HTTP reply we provide in ExpertLink, IntelliPay also has a second real-time data stream available for one-way replies, Silent Post – will you also use it?
- Log in to your Secure Account Management System (SAMS) and become familiar with your settings. The SAMS login is located at: https://www.intellipay.net/Merchant/
- Pay special attention to the LinkSmart configuration options in SAMS so that you can start to work out which fields to enable on our payment pages. Make any configuration changes you need to make in SAMS.
- Build your connector that will link your business or web systems to IntelliPay. This connector will take data you’ve gathered on your site, format it properly to talk to IntelliPay and open an HTTPS connection to us over the Internet for a real-time, two-way data exchange for payment processing.[You can also build other programmatic tools to manage today’s Open Batch, void transactions, and more. These additional tools may not be used during real-time processing but might be event-driven by business processes on your side. There are example implementations suggested later. Reviewing them may give you several powerful ideas in building more robust systems.]
- Test your implementation(s). You might have more than one product or package that can be purchased so may have more than one page that a customer might end up on. Test each page to be sure it links successfully and the data you sent appears on our payment pages. (Test accounts are available. Call for details.)
- Get out your credit card and run a live transaction from your system. Test the system fully. You can go into your Open Batch and Void those transactions (if you Void them before 8 p.m. Pacific Time), so they’ll never settle.Back to Top
|
Special Considerations
Your Merchant Account
You must have a merchant account to accept credit card payments. This account must be from a bank or other provider that offers accounts compatible with the private bank networks that IntelliPay supports. We support most of them so that part should be easy.If you already have a merchant account, contact your IntelliPay representative to confirm whether we support it and whether it’s suitable for Internet-based transactions.
If you don’t have a merchant account, your IntelliPay rep can refer you to several so you can make the best deal you can. However, you should also read our Special Report, “About Merchant Accounts” before you shop for these accounts.
IntelliPay works very hard to be “processor neutral”, which means that if you change merchant account providers in a way that also changes which bank network your provider uses, IntelliPay systems still behave the same way to your web site and applications. We still take advantage of every feature every bank network offers, but present them to you and your systems in the same ways. This makes IntelliPay completely portable for you.
About AVS
AVS (the “Address Verification System”) is a system run by the card associations (Visa and MasterCard) that compares the billing address given by your customer to the customer’s address on file in his credit card account. It verifies the street address number and the zip code to those two numbers in the cardholder’s file. If either is different, the AVS system returns a different AVS score to IntelliPay, and we return that score to you and log it in your batch. This non-perfect score is often called a “mis-match”.AVS is an important component in fraud detection. If the person using the card number does not know the correct address data and enters wrong data the AVS score will reflect it. Because it’s so important, your Internet-based merchant account from your bank requires that AVS be run on every transaction. If you don’t run AVS, or on transactions where AVS is not possible, your merchant account bank will charge you additional fees (non-qualified rates). IntelliPay helps save you money and increases your security against some fraudulent transactions by running AVS requests for you automatically.
AVS is only available for credit cards issued in the United States. This also means that transactions from your non-U.S. customer’s shopping with credit cards will result in additional fee(s) on your merchant account statement.
However, AVS is not always 100% accurate. One failing can be that American’s move their households and don’t always update their billing addresses in a timely manner.
Transactions will not be declined by the credit card systems because of an AVS mismatch. The card associations let you make this decision. You can accept an approved transaction that has AVS mis-matches and there can be many reasons to do so. You can also elect to reject all approved transactions because of AVS mis-matches.
IntelliPay gives you several ways to address the AVS issues, and possibly save you money by allowing you to automate how IntelliPay deals with AVS on your behalf. You can allow it to be a completely manual process where you see the AVS score in the e-mail receipts and go to your Open Batch and decide to call the customer, or let it settle normally or Void the transaction.
You can also take advantage of IntelliPay’s innovative HTML tags to tell us how to deal with AVS mis-matches, or tell us what the only acceptable AVS score is to you. See the tags “REJECTIFAVSNOT” and “REJECTAVSMISMATCH“. Also read our AVS document in our documentation section.
IntelliPay’s New Duplicate Transaction System
As a direct response to needs of some of our merchant customers, IntelliPay developed the Duplicate Transaction System (DTS). The DTS detects duplicate transaction attempts from your web site and responds based on rules you customize.There are many reasons duplicate attempts can happen on the Internet, some intentional and some accidental. Some merchants who offer online fulfillment in real-time, such as software downloads, credit to accounts and others, may also be prone to being victimized by fraudulent credit card attempts.
See our DTS documentation for details and how you can use DTS to your advantage. DTS is fully automated, but there are also methods for you to define what a duplicate actually is to you. Does a dupe mean card number and the amount, or just the card number? Also, we let you define how long before a duplicate attempt is OK, since the same cardholder may want to buy the same thing within your defined duplicate checking time window. Also see the LinkSmart field “DUPEOK“.
About Security and Credit Card Data on the Internet
If you have your own secure server and are keeping customer data on your machines, you must review your security issues. It is vital that you understand your risks related to credit card data on your web site. You can review more information about this topic in our Special Reports section.All communications to IntelliPay’s servers must be encrypted with minimally SSL 40 bit. Using LinkSmart properly will cause your shopper’s browsers to encrypt data from our payment pages back to our payment systems. We use industry standard security, including the more secure 128-bit SSL if the shoppers browser is configured for it.
Our data is fully secured behind 24 hour monitored firewalls and other high-level security precautions.
However, we are concerned with data security on your side also. Please read the various documents in our Reports section, and check out other links we’ve provided on this issue.
Basic Programming Requirements
The programming you build, whether inside a shopping cart or from a middle-ware connector must, at a minimum, accomplish the following things:
- Your connection tool must be able to send and receive HTTP over SSL – the standard httpS: protocol.
- Your site must produce a total transaction amount to be authorized by IntelliPay, as well as gather and/or transmit the necessary fields of data minimally required by IntelliPay. Other fields of data may be required by you as configured in your IntelliPay Secure Account Management System. Your programming would also have to provide those fields as well. (Calculating a total amount is not part of the IntelliPay Payment Gateway. Totals can be “hard coded” into your web pages, calculated by a shopping cart on your site, or calculated by script programming on your site.)
- Your web site must pass at least the fields marked with a single asterisk in the table below. These must be passed as typical HTML form fields (name/value pairs).
- Your programming must also be able to receive and parse our responses to your authorization request.
However, while there are minimum fields required by IntelliPay to process a transaction, they probably don’t suit the needs of your business or your merchant account. For instance, since Visa requires an invoice number with every transaction it makes sense to make INVOICE a required field. Likewise, sending us the full address fields, including ADDRESS and ZIP will fulfill your AVS requirements.
All Possible ExpertLink Fields and Definitions
The following fields can be passed to IntelliPay ExpertLink from your web site. And field names must be sent exactly as they are named below.
An single asterisk “*” denotes fields required by the IntelliPay payment system. Double asterisk “**” fields are heavily recommended. You may require other fields in your configuration. “***” fields are required if “TYPE” is set to “CR”
Note that Field Names and value options are case sensitive. Field names must all arrive as UPPER CASE. Value options must have upper/lower case as shown, i.e., “DelimitedList”.
Maximum Field Length column may include “A/N” meaning this field accepts alpha-numeric characters but NO non-printable characters.
Field Name |
Max Field Length
|
Definition and Notes |
**ADDRESS |
40
|
Customer’s street address (required for AVS)
|
*AMOUNT |
7
|
Amount of sale (include decimal point and 2 digits for cents), with or without a leading dollar sign. $#####.## is max size.
|
*CARDNUM |
19
|
All numeric credit card number. (Spaces and dashes between groups supported)
|
CITY |
60
|
Customer’s city
|
COUNTRYCODE | 2 | Customer’s Country |
CUSTID | 25 A/N | Optional. An alpha-numeric customer identifier that you assign to your customer |
CV2 | 1 |
Required if sending CV2VALUE. This field tells the IntelliPay gateway what the status of the CVV2 code is. You can pass the following values: 0 = CV2VALUE intentionally not provided |
CV2VALUE |
4
|
Optional Field. Used when sending the CVV / CVV2 (Card Verification Value) of a credit card. Intellipay will not decline a credit card if the CVV2 value does match, However, you can handle the CVV2 response programmatically and not allow the transaction to be processed. For more information click here. In addition to the CV2VALUE field, you also need to pass the fields CV2 and SENDCV2RESULT In order to get CVV results sent to you in the reply back to your server or via Silent Post you need to pass the field SENDCV2RESULT set to a value of Y If you don’t want CVV results returned to you you can set SENDCV2RESULT=N Please note: The digit length of the CV2VALUIE will vary depending on the type of credit card. Visa, Mastercard, Discover = 3 characters (i.e. 027 703 001, all have to have leading zeros) |
DEBUGLISTRESPONSE |
1
|
Optional field when merchant or merchant’s developer is debugging handling of the DelimitedList or NamedValueList returned from IntelliPay LinkSmart after a transaction. When set to “Y”, the DelimitedList or NamedValueList is wrapped in HTML.
|
DELIMCHARACTER |
1
|
Requires RECEIPTFORMAT to be set to value=”DelimitedList”. Use DELIMCHARACTER to set the delimiter used in the Delimited List that IntelliPay Payment Gateway returns.
Example: “<input type=”hidden” name=”DELIMCHARACTER” value=”,” …> |
DELIMCHARACTER2 |
1
|
Only works in returned field 3 (Decline Reason).
|
DELIMCHARACTER3 |
1
|
Only works in returned field 3 (Decline Reason).
|
DESCRIPTION |
255 A/N
|
Your text description of what your customer purchased.
|
DUPECHECK |
1
|
DUPECHECK instructs IntelliPay to check this transaction against the duplicate list when it is sent with the value Y. That is, sending DUPECHECK with the value Y guarantees that IntelliPay will check this transaction, regardless of your configuration. Conversely, DUPECHECK sent with the value N guarantees that IntelliPay will not check this transaction, again, regardless of your configuration. Read the Duplicate Transaction System documentation before use. |
DUPEOK |
1
|
Optional field. When you receive a RESPONSECODE of ‘S’, you can resubmit the transaction with DUPEOK set to “Y”. This will override the duplicate check. Read the Duplicate Transaction System documentation before use.
|
ECHODATA |
1
|
Optional field. When set to “Y” all name/value pairs submitted to the IntelliPay Payment Gateway are returned to merchant application.
|
100 A/N
|
Customer’s email address. Used when sending an email transaction receipt if configured in Merchant Configuration. (Required if merchant has configured Customer E-Mail Receipts in SAMS.
|
|
*EXPDATE | 4 or 5 |
(for credit cards) Credit Card expiration date. All numeric, no spaces. MMYY or MM/YY. Stored as “2001-03-26” (example)
|
FAX |
20 A/N
|
Customer’s fax number
|
**INVOICE |
25
|
An invoice number assigned by you or automatically assigned by the IntelliPay Payment Gateway. The IntelliPay Payment Gateway can generate unique invoice numbers, or can be set to require unique numbers. Settings are available in Merchant Configuration.
|
*LOGIN |
25 A/N
|
Merchant’s IntelliPay Payment Gateway Login ID
|
*METHOD |
2
|
Required Field for non-basic connections when serving your own payment page: Method of transaction. Must be a card or transaction type merchant is approved and configured for. Must read exactly as: “Visa” or “VI”, “MasterCard” or “MC”, “American Express” or “AX”, “Discover” or “NO”, “Diners” or “DI”, or “JC”.
|
NAME |
60 A/N
|
Customer’s name.
|
*PASSWORD |
12 A/N
|
Merchant’s IntelliPay LinkSmart Password (SmartTerminal Password is requires if “TYPE” is set to “CR”)
|
PHONE |
20
|
Customer’s phone number
|
*RECEIPTFORMAT |
Required Field: Value tells the IntelliPay Payment Gateway how to serve receipt data. Value must be one of the following:
Field order for DelimitedList and NamedValueList responses are available here. |
|
REJECTAVSMISMATCH |
1
|
If the AVSDATA value returned from the issuing bank contains anything other than X and Y, the IntelliPay Payment Gateway will reject this transaction, even if it was approved by the issuing bank.
|
REJECTIFAVSNOT |
11
|
Use REJECTIFAVSNOT to specify the set of acceptable AVS response codes; any transaction returned with some other AVS response code is “declined”. For example, if you set the value of REJECTIFAVSNOT to “XYZ”, IntelliPay will reject the transaction if the AVS response is not X, Y, or Z. (also see our AVS document for AVS code definitions) |
REGIONCODE |
2
|
Customer’s State
|
REGION | 255 A/N | Other Region field. This field must be passed if you specify a region code value of ZZ (Other Region). |
SENDCV2RESULT | 1 | Required when sending CV2 and CV2VALUE. This field tells the IntelliPay gateway if you want the results of the CVV2 check returned to you. Sending a value of Y will tell the gateway to send the results in the reply. Sending a value of N will tell the gateway that you do not want results returned to you. |
TRAILINGAMP |
1
|
Send this with a value of “N” to have the trailing “&” symbol removed from the end of the transaction results returned in the Silent POST.
|
*TYPE |
2
|
Type of transaction: either “NA” for Normal Authorization or “AO” for Authorization Only or “AI” (a – eye) for AVS Only or “CR” for Credit.
|
USER1 … USER10 |
255 A/N
|
Merchant-usable fields for passing information through the IntelliPay Payment Gateway. This data is not used by the IntelliPay Payment Gateway for transaction processing and are for the convenience of the merchant’s business process needs.
|
**ZIP |
20 A/N
|
Customer’s ZIP code (required for AVS)
|
***TRANSID |
13 A/N
|
Previous transaction ID
|
***ORIGAUTHCD |
6
|
Previous transaction Authorization Code
|
***ORIGAMOUNT |
7
|
Previous transaction Amount (include decimal point and 2 digits for cents), with or without a leading dollar sign. $#####.## is max size.
|
There are certain fields that give you dynamic control over the transaction itself at the time of the authorization request. How you configure and use these fields in ExpertLink will depend on the type of transaction you’re sending and/or business decisions based on your business model. There are also control fields in the Batch Management application detailed later which are:
DUPECHECK
DUPEOK
REJECTAVSMISMATCH
REJECTIFAVSNOT
TYPE
Transaction Types and Card Processing
The “TYPE” field contains 3 possible Values and each causes a different behavior after the request.
Value=”NA” means Normal Authorization. That transaction will behave as you may normally expect it to. The authorization code is returned and the transaction is moved into your Open Batch (viewable in SAMS), which will settle automatically that night.
Value=”AO” means Authorization Only. When authorized, this transaction will not be moved to your Open Batch, but instead will be moved to your Pending Batch. Merchants that can’t fulfill the order or ship on the same day as the authorization will usually AO the credit card, and later, when shipment has occurred, will go to the Pending Batch and mark the transaction for settlement that night. An ExpertLink protocol exists for managing the Pending Batch and is discussed later under Batch Management.
|
Value=”AI” means AVS Only. This is a new IntelliPay transaction type that lets you submit a transaction to validate the existence of a customer’s credit card account. Normally, this would not be used. However, if you are building a system that requires validating the account, this should be used. Any dollar amount submitted with an AI is irrelevant and will be ignored. This transaction does not settle and no charge against the customer’s account occurs. However, it is important to not run excessive AI’s against the same card.
Establishing Real-Time Two-Way Communication to ExpertLink
Your program or connector must talk HTTP over SSL to IntelliPay. Essentially, your program is imitating a standard web browser with SSL encryption in HTTP requests. For illustration purposes only, a block of the HTML code requesting a credit card authorization sent from your connector might contain the following elements:
<Form method=”POST” action=”https://www.intellipay.net/LinkSmart/”>
<!–Action must be httpS; method must be POST, never GET; “LinkSmart” is case sensitive–>
<INPUT Name=”LOGIN” Value=”MerchantIntelliPayLoginID”>
<INPUT Name=”PASSWORD” Value=”YourLinkSmartPassword”>
<INPUT Name=”AMOUNT” Value=”129.00″>
<INPUT Name=”CARDNUM” Value=”1234234534564567″>
<INPUT Name=”EXPDATE” Value=”0301″>
<INPUT Name=”TYPE” Value=”NA”>
<INPUT Name=”METHOD” Value=”VI”>
<INPUT Name=”RECEIPTFORMAT” Value=”NamedValueList”>
<INPUT Name=”NAME” Value=”John Doe”>
<INPUT Name=”ADDRESS” Value=”123 Somewhere St.”>
<INPUT Name=”CITY” Value=”Elsewhere”>
<INPUT Name=”REGIONCODE” Value=”AK”>
<INPUT Name=”ZIP” Value=”12345″>
<INPUT Name=”PHONE” Value=”(214) 222-3456″>
<INPUT Name=”EMAIL” Value=”jdoe@somewhereelse.com”>
<INPUT Name=”DESCRIPTION” Value=”Membership Package A”>
Fields Returned by ExpertLink
Real-time responses are controlled by your program sending the RECEIPTFORMAT field with one of the values “DelimitedList” or “NamedValueList”. In response to these requests you will receive the following fields:
(Note – Field names with an * are returned only if ECHODATA is set to “Y” when you submit your transaction request)
RESPONSECODE – To see all response codes, click here.
AUTHCODE – Authorization Code returned for this transaction.
DECLINEREASON – Message returned when a card is declined by the card issuing bank.
AVSDATA – AVS alphanumeric score as returned by card issuing bank network. To view the AVS response codes, click here.
CV2RESULT – CVV2 score returned by the card issuing bank network.
TRANSID – Unique transaction ID that is assigned to the transaction by the IntelliPay system.
LOGIN* – IntelliPay login name.
INVOICE* – Invoice number for the transaction.
AMOUNT* – Amount to be charged to the card.
METHOD* – Method of transaction. Values for the card types are:
VI – VISA.
MC – MasterCard.
NO – Discover.
AX – American Express.
DI – Diners Club.
JCB – JCB.TYPE* – Type of transaction. Values sent are:
NA – Normal Authorization to charge the card.
AO – Authorization Only .
AI – AVS Only.(Note – If no value is sent for the field of METHOD when you submit your transaction then “NA” will be used as the method.)
DESCRIPTION* – Description of the transaction.
CUSTID* – Alpha-numeric customer identifier that you assign to your customer
NAME* – Customer name.
ADDRESS* – Customer address. Required for AVS.
CITY* – Customer city.
REGIONCODE* – Customer state.
ZIP* – Customer ZIPCODE.
PHONE* – Customer contact phone number.
FAX* – Customer contact fax number.
EMAIL* – Customer e-mail address.
USER1 – 10* – Merchant-usable fields for passing information through the IntelliPay Payment Gateway. This data is not used by the IntelliPay Payment Gateway for transaction processing and are for the convenience of the merchant’s business process need.
Values of RESPONSECODE Field Returned by the IntelliPay Payment Gateway
The IntelliPay Payment Gateway will return one of the following values in the field RESPONSECODE. Anything other than ‘A’ indicates a failed transaction.
A
|
Approved. The purchase has been authorized by the issuer.
|
S
|
Same. The DTS has detected a possible duplicate transaction. You can treat this as a decline, or you can send the transaction again with the DUPEOK field set to “Y”.
|
D
|
Declined. The authorizer has declined the purchase request.
|
R
|
Referred. The issuer has asked that you call the Voice Authorization center.
|
X
|
Expired. The card has expired.
|
E
|
Error. A data entry error of some kind has occurred.
|
U
|
Unknown. An unknown processor or issuer error has occurred.
|
F
|
Failure. A system failure of some kind has occurred.
|
Rejecting a transaction based upon the CV2RESULT response code
About the CVV/CVV2 code
Mail order and telephone order (MO/TO) and other card-not-present transactions have higher fraud rates than face-to-face transactions. When a card’s magnetic stripe is read by a point-of-sale (POS) terminal, Visa’s Card Verification Value (CVV) or MasterCard’s Card Validation Code (CVC) can be verified during the authorization. However, when the card is not present the CVV or CVC cannot be validated. To help reduce fraud in the card-not-present environment, acquirers, merchants, and issuers can use the CVV2 or CVC2 program.
What is CVV2?
The CVV2 is a three-digit security code that is printed on the back of Visa, MasterCard and Discover cards. The number appears in reverse italic at the top of the signature panel at the end (located on the front of the card, top right on an American Express card).
This program helps validate that a genuine card is being used during a transaction. All MasterCard cards, both credit and debit, were required to contain CVC2 by January 1, 1997; all Visa cards must contain CVV2 by January 1, 2001.
Rejecting a transaction
When you post a transaction and include the named value pairs CV2, CV2VALUE and SENDCV2RESULT the field CV2RESULT will be returned in the reply. All available CV2RESULT response codes are as follows.
M
|
Match
|
N
|
No Match
|
P
|
Not Processed
|
U
|
Issuer not certified/Validation not available
|
S
|
Should be on card but not so indicated
|
X
|
No Response from association (Note: this response only applies to merchants that process through the FDC – First Data Corp. network)
|
Following is a sample code snipet of what the CV2 portion of your request should look like:
<input type=”hidden” name=”CV2″ value=”1″>
<input type=”hidden” name=”CV2VALUE” value=”123″>
<input type=”hidden” name=”SENDCV2RESULT” value=”Y”>
There are 3 different values that can be sent for the CV2 field:
1 |
My card has a legible code on it.
|
2
|
My code is illegible.
|
3 |
There is no code on my card.
|
The Intellipay gateway will not reject a transaction based on this code, therefore you would need to handle this programmatically to effectively reject a transaction based on the CV2RESULT.
To accomplish this you would first need to post your transaction with an AI (AVS Only) transaction type which will do an AVS check and return the CV2RESULT. You can then determine if you want to allow the transaction to go through based on the CV2RESULT value.
For instance, after posting an AI transaction and you receive a CV2RESULT value of N. You would then serve a page declining the transaction, if you receive an M response, you can then send a second request with the same information with a transaction type of NA (Normal Authorization) to actually get an authorization on the credit card.
Sending Data in an XML Request
The following is an overview of the XML request sent to the IntelliPay gateway. The URL is the standard https://www.intellipay.net/LinkSmart/.
The URL will take only one key/value pair passed as a POST where the key is�xmlrequest� and the value is the following:
<html>
<body>
<form method=POST action=”https://www.intellipay.net/LinkSmart/”>
<–This is what a complete XML request looks like.–>
<input type=text name=”xmlrequest” value='<PURCHASEREQUEST login=”your_login_here” password=”your_linksmart_password_here”
version=”1.0″>
<INVOICE>123456789</INVOICE>
<AMOUNT>29.99</AMOUNT>
<RECEIPTFORMAT>XmlReceipt</RECEIPTFORMAT>
<CARDNUM>4111111111111111</CARDNUM>
<EXPDATE>12/15</EXPDATE>
<TYPE>NA</TYPE>
<METHOD>VI</METHOD>
<DESCRIPTION>Purchase of a widget</DESCRIPTION>
<CUSTID>johndoe</CUSTID>
<NAME >John Doe</NAME>
<ADDRESS>123 Down Lane</ADDRESS>
<CITY>Springfield</CITY>
<STATE>Ohio</STATE>
<COUNTRY>US</COUNTRY>
<ZIP>55555</ZIP>
<ECHODATA>Y</ECHODATA>
</PURCHASEREQUEST>’>
<input type=submit value=Submit Transaction>
</form>
</body>
</html>
Explanation of structure
The <PURCHASEREQUEST> tag contains the entire request being sent to the IntelliPay gateway. <PURCHASEREQUEST> will also have three attributes, login, password, and version. The values for login and password will be different for each merchant website using the IntelliPay service. Where the PURCHASEREQUEST follows the form described in this document, the version will be �1.0�. Nineteen (19) fields will be associated with this request, seven (7) required and twelve (12) optional. The <PURCHASEREQUEST> tag breakdown is as follows:
Required Fields
The <INVOICE> tag contains the alphanumeric invoice code (10 characters maximum).
The <AMOUNT> tag holds the amount of the transaction in digits (8 characters, consisting of 5 characters followed by a decimal point followed by 2 characters).
The <RECEIPTFORMAT> tag holds the receipt format specification and must be: XmlReceipt
The <CARDNUM> tag holds the creditcard number.
The <EXPDATE> tag contains the credit card expiration date.
The <METHOD> tag holds information relating to the type of credit card used and will contain one of six (6) valid entires:
VI – VISA.
MC – MasterCard.
NO – Discover.
AX – American Express.
DI – Diners Club.
JCB – JCB.
The <TYPE> tag contains transaction codes in one of three (3) valid entries:
NA – Normal Authorization to charge the card.
AO – Authorization Only .
AI – AVS Only.
Optional Fields
The <DESCRIPTION> tag contains a textual description of the transaction (255 characters maximum).
The <CUSTID> tag contains a string that identifies a purchaser (25 characters maximum).
The <NAME> tag holds a string with the purchaser’s name (30 characters maximum).
The <ADDRESS> tag contains the street address for the purchaser as a string (40 characters maximum).
The <CITY> tag holds a string with the name of the purchaser’s city of residence (60 characters maximum).
The <STATE> tag holds the name of the purchaser’s state of residence as a string (60 characters maximum).
The <COUNTRY> tag holds a string containing the purchaser’s country name (100 characters maximum).
The <ZIP> tag contains the postal code of the purchaser’s residence as a string (20 characters maximum).
The <PHONE> tag holds the purchaser’s phone number as a string (20 characters maximum).
The <FAX> tag contains the purchaser’s fax number as a string (20 characters maximum).
The <EMAIL> tag holds the purchaser’s email address as a string (100 characters maximum).
The <ECHODATA> tag contains a value of �Y� indicating that all �receipt� fields will be included in the return.
Example request
<PURCHASEREQUEST login=”your_login_here” password=”your_linksmart_password_here” version=”1.0″>
<INVOICE>123456789</INVOICE>
<AMOUNT>29.99</AMOUNT>
<RECEIPTFORMAT>XmlReceipt</RECEIPTFORMAT>
<CARDNUM>4111111111111111</CARDNUM>
<EXPDATE>12/15</EXPDATE>
<TYPE>AO</TYPE>
<METHOD>VI</METHOD>
<DESCRIPTION>Purchase of a widget</DESCRIPTION>
<CUSTID>johndoe</CUSTID>
<NAME >John Doe</NAME>
<ADDRESS>123 Down Lane</ADDRESS>
<CITY>Springfield</CITY>
<STATE>Ohio</STATE>
<COUNTRY>US</COUNTRY>
<ZIP>55555</ZIP>
<ECHODATA>Y</ECHODATA>
</PURCHASEREQUEST>’>
XML Response
The following is an overview of the XML response that the IntelliPay gatewaywill return. Please note that the indentation and carriage returns are for readability purposes only. The response type will be that of Content-type: text/xml . There will be no HTML in the response.
<PURCHASERESPONSE version=�1.0� >
<RESPONSECODE ></RESPONSECODE>
<AUTHCODE ></AUTHCODE>
<AVSDATA ></AVSDATA>
<TRANSID></TRANSID>
<PHONE ></PHONE>
<FAX ></FAX>
<EMAIL ></EMAIL>
</ PURCHASERESPONSE>
If a data validation (edit) error occurs, the system will reply with a response code of �E� and send an error code within the <ERRORCODE> tag and an error message string within the <ERRORMESSAGE> tag.
If a system error occurs, the system will reply with a response code of �F� and send an error message string within the <ERRORMESSAGE> tag.
<PURCHASERESPONSE version=�1.0�>
<RESPONSECODE></RESPONSECODE>
<ERRORCODE></ERRORCODE>
<ERRORMESSAGE></ERRORMESSAGE>
</PURCHASERESPONSE>
Explanation of structure
The <PURCHASERESPONSE> tag contains the entire response from the IntelliPay gateway. The PURCHASERESPONSE has a single attribute, version. The version described in this document is version 1.0. The PURCHASERESPONSE reports either the details of a successful transaction or the reason for a failed transaction. The five (5) tags always associated with the response include:
The <RESPONSECODE> tag holds a string containing information relating to the success or failure of the transaction (3 character maximum). The possible values of RESPONSECODE are listed below:
A – Approved.
D – Declined.
E – Error in Data.
F – Failure.
R – Referred; Call Merchant Services.
S – Same as Previous (Duplicate).
U – Unknown Failure Response.
X – Expired Card.
The <AUTHCODE> tag contains an alpha-numeric string with the authorization code (6 character maximum).
The <AVSDATA> tag contains a string with the rating the address verification system (AVS) gave to the address submitted for the cardholder (1 character maximum). The possible values of AVSDATA are
Click here for a list of AVS response codes
The <TRANSID> tag contains a transaction identifier code string (50 character maximum).
The <MESSAGE> tag may contain an explanatory message when the RESPONSECODE has any value other than �A�.
A number of fields are added to the PURCHASERESPONSE if the value of ECHODATA was set to �Y� in the PURCHASEREQUEST. Those fields, described in the PURCHASEREQUEST section, are:
The <INVOICE> tag contains the alphanumeric invoice code (10 characters maximum).
The <AMOUNT> tag holds the amount of the transaction in digits (8 characters, consisting of 5 characters followed by a decimal point followed by 2 characters).
The <METHOD> tag holds information relating to the type of credit card used and will contain one of six (6) valid entires:
VI – VISA.
MC – MasterCard.
NO – Discover.
AX – American Express.
DI – Diners Club.
JCB – JCB.
The <TYPE> tag contains transaction codes in one of three (3) valid entries:
NA – Normal Authorization to charge the card.
AO – Authorization Only .
AI – AVS Only.
The <DESCRIPTION> tag contains a textual description of the transaction (255 characters maximum).
The <CUSTID> tag contains a string that identifies a purchaser (25 characters maximum).
The <NAME> tag holds a string with the purchaser’s name (30 characters maximum).
The <ADDRESS> tag contains the street address for the purchaser as a string (40 characters maximum).
The <CITY> tag holds a string with the name of the purchaser’s city of residence (60 characters maximum).
The <STATE> tag holds the name of the purchaser’s state of residence as a string (60 characters maximum).
The <ZIP> tag contains the postal code of the purchaser’s residence as a string (20 characters maximum).
The <COUNTRY> tag holds a string containing the purchaser’s country name (100 characters maximum).
The <PHONE> tag holds the purchaser’s phone number as a string (20 characters maximum).
The <FAX> tag contains the purchaser’s fax number as a string (20 characters maximum).
The <EMAIL> tag holds the purchaser’s email address as a string (100 characters maximum).
Example Responses
Where ECHODATA was set to �Y� in the original PURCHASEREQUEST:
<PURCHASERESPONSE>
<RESPONSECODE>A</RESPONSECODE>
<AUTHCODE>AC35DE </AUTHCODE>
<AVSDATA>Z</AVSDATA>
<TRANSID>C00 123456789</TRANSID>
<INVOICE>123456789</INVOICE>
<AMOUNT>29.99</AMOUNT>
<METHOD>VI</METHOD>
<TYPE>AO</TYPE>
<DESCRIPTION>Purchase of a widget</DESCRIPTION>
<CUSTID>johndoe</CUSTID>
<NAME>John Doe</NAME>
<ADDRESS>123 Down Lane</ADDRESS>
<CITY>Springfield</CITY>
<STATE>Ohio</STATE>
<ZIP>55555</ZIP>
<COUNTRY>USA</COUNTRY>
<PHONE>5555555555</PHONE>
<FAX>5555555554</FAX>
<EMAIL>jdoe@email.com</EMAIL>
</PURCHASERESPONSE>
or
<PURCHASERESPONSE>
<RESPONSECODE>F</RESPONSECODE>
<ERRORCODE>100</ERRORCODE>
<ERRORMESSAGE> A system failure has occurred.</ERRORMESSAGE>
</PURCHASERESPONSE>
Remote Messaging for Batch Management
Using Batch Management, a merchant can Void and/or settle (capture) transactions previously authorized as Authorization Only (“AO”) that were stored in the Pending Batch. Batch Management provides a tool allowing more complete programmatic control from your side.
Using your programmed connector you send an HTTPS request to:
https://www.intellipay.net/BatchManagement/ (case sensitive),
with input fields as follows (Case sensitivity exactly as shown):
<INPUT Name=”LOGIN” Value=”YourLoginIDHere”>
<INPUT Name=”PASSWORD” Value=”YourSmartTerminalPassword”>
<INPUT Name=”RECEIPTFORMAT” Value=”NamedValueList or DelimitedList”>
<INPUT Name=”TRANSID” Value=”C00 3241″ (example transid code)And one of:
(Note – Field names and Values are case sensitive)
<INPUT Name=”Void” Value=”Void”>
or
<INPUT Name=”PreAuthCompletion” Value=”PreAuthCompletion”>
You obtain the Transaction ID from an IntelliPay ExpertLink list response (DelimitedList position 5, or NamedValueList tag of TRANSID) or from Silent Post (discussed later). The transaction ID is alphanumeric with a variable length up to 25 characters. In replies you TRANSID may contain any printable characters including spaces. Trailing spaces are not significant.
Each void or settle transaction requires a separate HTTPS POST. These transactions use your Smart Terminal Password, not your LinkSmart password.
The possible Response Codes returned from Batch Management are:
S – Successfully Settled or Voided
E – Error. Either the transaction ID is invalid or the transaction has already been settled or voided.
Silent Post – An Additional Real-Time Reply Tool
Silent Post is an additional method of receiving a reply from a real-time authorization request when using LinkSmart or ExpertLink. It is one-way only, and operates independently of ExpertLink’s normal reply to the requesting https connection.
Silent Post effectively gives you another way to target reply data and can be used for any number of applications. It can be targeted any application that you can specify a URL for anywhere on the web. This means that it can be used to update inventory, sales systems or even POST to an application living at your fulfillment house or another corporate location.
The Silent Post occurs immediately before ExpertLink replies to the https connection, but for most practical purposes these two data streams can be viewed as simultaneous.
Silent Post imitates a browser and POSTs to the URL you configure in SAMS. In your Secure Account Management System (SAMS) you will find a field “Silent POST Script URL”. In this field you can enter the URL of a script or program that Silent Post should send it’s reply to.
The fields returned in the Silent Post are listed in the table below. The reply is sent as an HTTP POST containing name/value pairs in the string. Your application receiving the replies will parse this HTTP string to extract the responses.
Fields Returned via Silent Post
(Note – Field names with an * are returned only if ECHODATA is set to “Y” when you submit your transaction request)
RESPONSECODE – To see all response codes, click here.
AUTHCODE – Authorization Code returned for this transaction.
DECLINEREASON – Message returned when a card is declined by the card issuing bank.
AVSDATA – AVS alphanumeric score as returned by card issuing bank network. To view the AVS response codes, click here.
CV2RESULT – CVV2 score returned by the card issuing bank network.
TRANSID – Unique transaction ID that is assigned to the transaction by the IntelliPay system.
LOGIN* – IntelliPay login name.
INVOICE* – Invoice number for the transaction.
AMOUNT* – Amount to be charged to the card.
METHOD* – Method of transaction. Values for the card types are:
VI – VISA.
MC – MasterCard.
NO – Discover.
AX – American Express.
DI – Diners Club.
JCB – JCB.TYPE* – Type of transaction. Values sent are:
NA – Normal Authorization to charge the card.
AO – Authorization Only .
AI – AVS Only.(Note – If no value is sent for the field of METHOD when you submit your transaction then “NA” will be used as the method.)
DESCRIPTION* – Description of the transaction.
CUSTID* – Alpha-numeric customer identifier that you assign to your customer
NAME* – Customer name.
ADDRESS* – Customer address. Required for AVS.
CITY* – Customer city.
REGIONCODE* – Customer state.
ZIP* – Customer ZIPCODE.
PHONE* – Customer contact phone number.
FAX* – Customer contact fax number.
EMAIL* – Customer e-mail address.
USER1 – 10* – Merchant-usable fields for passing information through the IntelliPay Payment Gateway. This data is not used by the IntelliPay Payment Gateway for transaction processing and are for the convenience of the merchant’s business process need.