|
KeyIC ConneX
- Supports auth, sale, refund and rebilling (subscriptions) transactions
- Supports Credit Card CVV2 validation
- Supports Crypto-Hash encryption for transaction
validation and security
A sample ASP page with submission
form and response decoding using the KeyIC ConneX component is included.
Property/Method Summary
|
Accessing the Nelix.KeyICGateway
Active X Object
|
| From VB Script |
dim gatewayObj
set gatewayObj = server.createobject("Nelix.KeyICGateway")
|
| From VBA |
dim gatewayObj
As Nelix.KeyICGateway
Set gatewayObj = New Nelix.KeyICGateway
|
|
Input Properties
|
accountSiteTag
(required) |
This field is comprised of two components
- the Account Number and the Site Tag. The Account Number
is the unique identifier for a merchant account in the KeyIC
system. It allows the transaction to be tracked and credited
to the appropriate merchant. The Site Tag is a tool that
can be used to allow multiple applications to use the same gateway
account and be tracked separately. These can be configured
from within the gateway
administration.
Format:
"Account:SiteTag"
Example setting: "132323332231:keyic"
Example Syntax: gatewayObj.AccountSiteTag="132323332231:keyic"
|
authType
(required) |
This is the kind of authorization that
will be executed by the KeyIC system.
- 'Auth' transactions only verify
that the payment method is valid, it does not do an actual
charge. This type of transaction is NOT supported by ACH (Checks)
- 'Sale' does an actual charge.
- 'Refund' issues a refund on
an existing transaction.
- 'Rebilling' is when a recurring
transaction is needed (monthly, quarterly, etc).
Valid settings:
- "Auth"
- "Sale"
- "Refund"
- "Rebilling"
Example Syntax:
gatewayObj.AuthType
= "Sale"
|
billingAddress
(Not needed for refund) |
This is a comma separated list
of the billing address to be used for validation. Each
of these fields can also be set individually.
Format: "Name1, Name2,
Street, City, State, Zip, Country, Phone, Email"
Example Setting: "Brian,
Jones,1350 Red Oak Drive, Schaumburg, IL,60173, US,847-781-9186,bjones@home.com"
Example Syntax: gatewayObj.BillingAddress="
Brian, Jones,1350 Red Oak Drive, Schaumburg, IL,60173, US,847-781-9186,bjones@home.com"
|
checkInfo
not needed for refund. relates
to ACH transactions only) |
This takes a comma separated list of the
check information to be used in an ACH transaction. A 'Sale' transaction can be paid
with either an ACH transaction or a credit card transaction. ACH can be used for a 'Rebilling' if the initial amount is greater than $0. Each of these fields can also be set individually, optional
fields are indicated in red.
Format: "Routing,
Account, Checknumber, SSN, TaxID, DL
(driver's license), DLState"
Example Setting: "12341211,3243004322,1209"
Example Syntax: gatewayObj.CheckInfo="12341211,3243004322,1209"
|
creditInfo
(not needed for refund. relates
to credit card transactions only) |
This takes a comma separated list
of the credit card information to be used in a credit card transaction.
Each transaction can be either an ACH transaction or a credit
card transaction. Each
of these fields can also be set individually, optional fields
are indicated in red.
The CVV2 number is a 3 or 4 digit number found on the signature
side of a credit card after the credit card number.
Format: "Ccnumber,
Ccexpire (MMYY format), Cvv2 "
Example Setting: "1234123412341234,1202"
Example Syntax: gatewayObj.CreditInfo="1234123412341234,1205"
|
encryptionKey
(required if "crypto-hash"
is turned on through the gateway.) |
This is used if the merchant decides to use
the optional "Crypto-Hash" feature of the gateway.
Crypto-Hash is a proprietary technology that is used to ensure
a transaction is not tampered with in transit. See below
for a more complete description of Crypto-Hash. If Crypto-Hash
is used, an encryption key is generated in the gateway and must
be included here.
Example Setting: "1gh23kdf323r5"
Example Syntax: gatewayObj.encyrptionKey="1gh23kdf323r5"
|
encryptionFields
(required if "crypto-hash"
is turned on through the gateway.) |
This is a comma separated list of field names
that is used to provide additional transactional security.
For a listing of valid field names see below in the Individual
Fields section.
Example Setting: "amount,ccnumber,ccexpire"
Example Syntax: gatewayObj.encryptionFields="amount,ccnumber,ccexpire"
|
rebillingInfo
(required for rebilling only) |
This is a comma separated string of values
related to creating a subscription authorization. When a 'Rebililng' is sent to the KeyIC system it will be converted into an 'Auth' or 'Sale' transaction depending
on whether you specify an initial amount. Please note if paying a rebilling by ACH (check) that the initial amount must be greater than $0. Fields
are:
- Duration: Number of days in the initial subscription period
(i.e. 30 days before 1st rebilling)
- Login: Login name selected by the user for our system
(must be unique for each user).
- Password: Password selected by the user for our system.
- Rebill: KeyIC system setting, set to 1 to start a rebilling
on this transaction or 0 to not do rebilling (typically
is set to 1).
- RebillCount: Number of rebilling to occur (i.e. 11 rebillings
in a yearly subscription)
- Period: Number of days in between rebillings or an SQL
Date expression (i.e. 30 days between a monthly rebilling)
- RebillAmount: Cash amount to charge at each rebilling
- Prorate: (optional) If a
value of 1 is passed, then you can pass an SQL Date expression
to 'Period' and get the charge prorated. (e.g. if they start
a subscription in the middle of the month)
Format: "Duration,Login,Password,Rebill,
RebillCount,Period,Rebillamount,Prorate"
Example Setting: "30,bjones,lucky123,1,12,20,25.99"
Example Syntax: gatewayObj.rebillingInfo="30,bjones,lucky123,1,12,20,25.99"
|
refundId
(required for refund only) |
This is the unique identifier from any transaction
(Trans ID) that will be used by the KeyIC system to attempt
a refund.
Example setting: "1233219823942342"
Example Syntax: gatewayObj.refundId="1233219823942342"
|
receiptInfo
(not needed for refund) |
This is the key information about the actual
charge/authorization. A comma separated string with the cost
first followed by a description to be recorded by the KeyIC
system to help identify the transaction purpose.
Format: "Amount,Description
"
Example setting: "125.00,Sale at www.widgets.com"
Example Syntax: gatewayObj.receiptInfo="125.00,Sale
at www.widgets.com"
|
| Individual Fields |
This is a listing of all the individual
fields that can be set on their own if you do not want to use
the 'grouped' properties above. These are also the field
names to be used when setting the encryptionFields property.
All fields are trimmed of excess spaces when they are assigned.
Also the phone, ccnumber, ccexpire, ssn, taxid, DL, Amount and
Rebillamount fields are stripped of extra characters: $ - (
)
- Name1
- Name2
- Street
- City
- State
- Zip
- Country
- Phone
- Email
- Amount
- Description
- Ccnumber
- Ccexpire
- CVV2
- Routing
- Account
- Checknumber
- SSN
- TaxID
- DL
- DLState
- Duration
- Login
- Password
- Rebill
- RebillCount
- Period
- RebillAmount
- Prorate
|
|
Response Properties
|
| errorInformation |
This will return any of the error messages
that are active.
|
responseBody
(read only) |
This is the native response body from the KeyIC system if you so choose
to extract information directly from it. It can provide additional information
in cases where atypical error messages are generated.
|
responseValues
(valueName as String) |
This method will return a specific response
field or all field values returned by the KeyIC system. The
primary field of concern is the 'Status' field, it will return
a value of 'successful' or 'failed'. The 'Trans_id' is the unique
identifier for any transaction. The '_msg' fields will
contain human readable values to indicate how different types
of transactions proceeded. The Avs fields relate to the
address verification part of the transaction. Valid field names:
- Status
- Trans_id
- Auth_msg
- Auth_code
- Avs_code
- Avs_msg
- Card_issuer
- CVV2_code
- CVV2_msg
- All (will return all information in a code=value
comma separated list)
|
| Version |
Basic version information on the KeyIC gateway
component.
|
|
Methods
|
| execute |
This is the method that will validate the
request and send it to the KeyIC system. If the request is valid
the execute method returns true, and the transaction is sent
to the KeyIC system. The KeyIC system may then return
a 'successful' or 'failed' transaction along with the associated
response fields above. if the request is invalid the execute
method returns false and then you can access the errorInformation
property to determine the problem. |
|
Crypto-Hash Information
|
|
Although transaction information
is sent via SSL (https://) connection, this alone is not enough
to ensure security. A knowledgeable user may try to get free
products or services from an online company by changing the
information submitted to our system. It's a relatively simple
matter to copy the HTML source of your shopping cart's submittal
page, then instead of submitting the correct price for your
product, submit a lower (or $1.00) price.
Fortunately, we have a method for preventing this sort of
attack. We use a crypto-hash function to ensure the data has
not been tampered with between your system and ours. It's
based on MD5, a strong cryptographic hashing algorithm developed
by RSA Data Security, Inc.
First, you need to know your account's Crypto-hash Key. This
is the Key your system will use to encode the crypto-hash
value you will be sending to our system. This can be found
on the Crypto-hash screen in our Admin tools.
It is VERY important that this number is kept confidential.
If anyone gets access to the crypto-hash key, they can break
into the system just as easily as if you weren't using it.
If you believe your key has been compromised, return to the
setup page and generate a new one immediately! Then remember
to update any CGI scripts that have the key hard coded to
reflect the new key value.
Next, you need to decide which fields are important, and
should be protected. Generally, this would be the total of
the transaction, maybe a credit card or check routing number,
address and so on. If you do rebillings and member signups,
you may want to include the related rebilling prices information,
as well. You have to choose at least TWO fields. Crypto-Hash
is unreliable when used on only one field. If you do not supply
any encryption fields the KeyIC dll will choose them for you.
The final step will require the developer to set the encryption
key and encryption fields properties and KeyIC ConneX will take care of the encryption. Note the encryptionFields
property takes a comma separated list of the field names you
want as part of the encryption. KeyIC ConneX will retrieve
the values associated with those fields and encrypt the field
values, not the field names.
When the transaction is processed by the KeyIC gateway using
Crypto-Hash the KeyIC system will run the same Hash process
on the fields specified in encryptionFields and compare the
result between your hash and its hash. If there is not a match,
it indicates tampering and the transaction will fail.
|
|
