Helcim Gateway
Ingenico i5100
Resources
Developer Documentation
Support - Helcim Gateway
For development support or to acquire a developer test account for the Helcim Gateway, contact us today.
Downloadable Format
Table of Contents
- Introduction
- Request Variables (Form Sample)
- Optional Variables (Form Sample)
- Response Variables
- AVS Response Codes
- CVV2 Response Codes
- Error Testing Codes
- AVS Response Test Codes
- CVV2 Response Test Codes
- Recurring Transactions
- Request Variables (Recurring) (Form Sample)
Copyright © 2006 - 2009 Helcim Inc. All rights reserved.
The information contained in this document is subject to change without notice.
This document contains information protected by copyright.
NO PART OF THIS DOCUMENT MAY BE PHOTOCOPIED OR REPRODUCED IN ANY FORM WITHOUT PRIOR WRITTEN CONSENT FROM HELCIM INC.
Introduction
The Helcim Gateway gives merchants a more integrated payment processing solution. It allows merchants to make a direct connection with our processing gateway to create a truly customized payment solution. The Helcim Gateway is for merchants who have, or will hire someone, with the knowledge of the development and security requirements involved with programming for a processing gateway.
Purpose of This Document
The purpose of this document is to outline the functionality of the processing gateway, and how it's accessed.
Requirements
In order to use the Helcim Gateway you will require the following:
- Knowledge of the Payment Card Industry Data Security Standard and how it will apply to your situation.
- A valid SSL certificate.
- A server with a scripting language capable of sending and receiving an HTTP connection and POST/GET variables.
- Knowledge of HTML.
- Knowledge of a server-side scripting language (PHP, ASP, JSP, etc...)
Development Process
The recommended steps to follow when developing for the Helcim Gateway are:
- Create your token in the Gateway Administration Tool.
- Use the HTML form samples included in this document to layout your solution.
- Integrate your solution into a server-side scripting language.
- Use the development environment to test your solution.
- When everything is functioning as expected, change your solution over to the production environment.
Production Environment
The URL to connect to the Helcim Gateway is:
https://gateway.helcim.com/
Development Environment - Active Merchants
You can switch between development and production environments by sending the "test" variable along with your transaction request. A value of "1" will send the transaction through the development environment. If the "test" variable is not included in the request, or is set to anything other than "1" the transaction will be processed through the production environment.
Development Environment - Developer Merchants
Development-specific accounts must use a separate gateway test environment located at:
https://gatewaytest.helcim.com/
Request Variables
*** NOTICE: All fields are case-sensitive.
| merchantId | numeric | Your merchant id; must not include any spaces or special characters. |
| token | alpha | Your Gateway token (generated within the Gateway Administration Tool). |
| type | alpha | Type of transaction to be processed. Must be either: purchase, refund or void. |
| amount | 10,2/decimal | Amount to process. Must include two decimal places, and must NOT include $. |
| cardNumber | 16/numeric | Credit card number; must not include any spaces or special characters. |
| expiryDate | 4/numeric | Credit card expiry date in the form of MMYY. With leading zeroes if the month or year is only one digit. |
| cvvIndicator | 1/numeric | CVV2 presence indicator. Must be either 1, 2 or 3 (1 = present, 2 = not visible, 3 = not present) |
| cvv | 4/numeric | CVV2 value. |
| cardholderName | 100/alpha | Name on card. |
| cardholderAddress | 255/alpha | Address of cardholder for address verification. |
| cardholderPostalCode | 50/alpha | Postal code/zip code of cardholder for address verification. |
| transactionId | 10/numeric | The transaction id of the transaction to void (this field is only required for a void). |
| test | 1/numeric | Sets whether this is a test transaction or not. Any value other than 1 will assume this is a real transaction. |
Form Sample
Below is an HTML form sample with all the required fields for processing a transaction:
<form action="https://gateway.helcim.com/" method="POST"> <input type="hidden" name="merchantId" value="<your_merchant_id>"> <input type="hidden" name="token" value="<your_gateway_token>"> <input type="hidden" name="test" value="1"> <input type="hidden" name="type" value="purchase"> <input type="hidden" name="amount" value="10.00"> <input type="hidden" name="cardholderName" value="John Doe"> <input type="hidden" name="cardNumber" value="4242424242424242"> <input type="hidden" name="expiryDate" value="0315"> <input type="hidden" name="cvvIndicator" value="1"> <input type="hidden" name="cvv" value="123"> <input type="hidden" name="cardholderAddress" value ="111 25th Ave"> <input type="hidden" name="cardholderPostalCode" value="T2S3G4"> <input type="submit" name="submit" value="Submit"> </form>
Optional Variables
Billing Information
| billingName | 100/alpha | Customer's billing name. |
| billingAddress | 255/alpha | Customer's billing address. |
| billingCity | 255/alpha | Customer's billing city. |
| billingProvince | 255/alpha | Customer's billing province or state. |
| billingPostalCode | 50/alpha | Customer's billing postal code or zip code. |
| billingCountry | 255/alpha | Customer's billing country. |
| billingPhoneNumber | 255/alpha | Customer's billing phone number. |
| billingEmailAddress | 255/alpha | Customer's billing email address. |
Shipping Information
| shippingName | 100/alpha | Customer's shipping name. |
| shippingAddress | 255/alpha | Customer's shipping address. |
| shippingCity | 255/alpha | Customer's shipping city. |
| shippingProvince | 255/alpha | Customer's shipping province or state. |
| shippingPostalCode | 50/alpha | Customer's shipping postal code or zip code. |
| shippingCountry | 255/alpha | Customer's shipping country. |
| shippingPhoneNumber | 255/alpha | Customer's shipping phone number. |
| shippingEmailAddress | 255/alpha | Customer's shipping email address. |
Order Information
| orderId | 50/alpha | Unique transaction identifier, transaction will fail if a duplicate order id is found. The order id will be automatically generated by the Gateway if this field is blank. |
| customerId | 50/alpha | Customer identifier. |
| comments | alpha | Any extra information from the cardholder or merchant. |
| itemId# | 50/alpha | Item SKU. |
| itemDescription# | 255/alpha | Item description. |
| itemQuantity# | 4,2/decimal | Item quantity, must be at least one for item to be added. |
| itemPrice# | 10,2/decimal | Item price per each. |
| itemTotal# | 10,2/decimal | Item price X quantity. |
| shippingAmount | 10,2/decimal | Total shipping amount. |
| taxAmount | 10,2/decimal | Total tax amount. |
Form Sample
Below is an HTML form sample with all the required fields for processing a transaction as well as optional fields:
<form action="https://gateway.helcim.com/" method="POST"> <!-- Required Fields --> <input type="hidden" name="merchantId" value="<your_merchant_id>"> <input type="hidden" name="token" value="<your_gateway_token>"> <input type="hidden" name="test" value="1"> <input type="hidden" name="type" value="purchase"> <input type="hidden" name="amount" value="18.00"> <input type="hidden" name="cardholderName" value="John Doe"> <input type="hidden" name="cardNumber" value="4242424242424242"> <input type="hidden" name="expiryDate" value="0315"> <input type="hidden" name="cvvIndicator" value="1"> <input type="hidden" name="cvv" value="123"> <input type="hidden" name="cardholderAddress" value ="111 25th Ave"> <input type="hidden" name="cardholderPostalCode" value="T2S3G4"> <!-- Billing Information --> <input type="hidden" name="billingName" value="Billing Name"> <input type="hidden" name="billingAddress" value="Billing Address"> <input type="hidden" name="billingCity" value="Billing City"> <input type="hidden" name="billingProvince" value="Billing Province"> <input type="hidden" name="billingPostalCode" value="Billing PC"> <input type="hidden" name="billingCountry" value="Billing Country"> <input type="hidden" name="billingPhoneNumber" value="Billing Phone"> <input type="hidden" name="billingEmailAddress" value="example@example.com"> <!-- Shipping Information --> <input type="hidden" name="shippingName" value="Shipping Name"> <input type="hidden" name="shippingAddress" value="Shipping Address"> <input type="hidden" name="shippingCity" value="Shipping City"> <input type="hidden" name="shippingProvince" value="Shipping Province"> <input type="hidden" name="shippingPostalCode" value="Shipping PC"> <input type="hidden" name="shippingCountry" value="Shipping Country"> <input type="hidden" name="shippingPhoneNumber" value="Shipping Phone"> <input type="hidden" name="shippingEmailAddress" value="example@example.com"> <!-- Order Information --> <input type="hidden" name="customerId" value="customer1"> <input type="hidden" name="itemId1" value="SKU1"> <input type="hidden" name="itemDescription1" value="Product 1"> <input type="hidden" name="itemQuantity1" value="2"> <input type="hidden" name="itemPrice1" value="5.00"> <input type="hidden" name="itemTotal1" value="10.00"> <input type="hidden" name="itemId2" value="SKU2"> <input type="hidden" name="itemDescription2" value="Product 2"> <input type="hidden" name="itemQuantity2" value="1"> <input type="hidden" name="itemPrice2" value="5.00"> <input type="hidden" name="itemTotal2" value="5.00"> <input type="hidden" name="comments" value="Order comments."> <input type="hidden" name="shippingAmount" value="1.00"> <input type="hidden" name="taxAmount" value="2.00"> <input type="submit" name="submit" value="Submit"> </form>
Response Variables
Each response variable is returned as a value pair (i.e.: response=1). Each value pair is separated by a carriage-return and line feed. If the responseMessage or noticeMessage variables contain more than one error, each error is further separated by a line feed.
| orderId | 50/alpha | Order id. If set in request, response will be the same. |
| response | 1/numeric | 1 = approved, 0 = declined |
| responseMessage | alpha | Response description. |
| noticeMessage | alpha | This will be returned if there was a problem with an optional request variable. For example if the billingName is over 100 characters, it will be truncated and a message will be displayed here. |
| date | yyyy-mm-dd | Date transaction was processed in the format of: yyyy-mm-dd. |
| time | ##:##:## | Time transaction was processed in the format of: ##:##:##. |
| type | alpha | Transaction type. |
| cardholderName | 100/alpha | Name of card holder. |
| amount | 10,2/decimal | Transaction amount. |
| cardNumber | 12/alpha | First four and last four digits of the card number in the format of: ####****####. |
| transactionId | 10/numeric | Transaction identifier. |
| expiryDate | 4/numeric | Card expiry date if the format of: MMYY. |
| cardType | alpha | Type of card used in transaction (i.e. Visa, MasterCard) |
| avsResponse | 1/alpha | Address verification response. |
| cvvResponse | 1/alpha | CVV2 verification response. |
AVS Response Codes
| A | Address (street) matches, ZIP does not. |
| B | Street address match, postal code in wrong format. (International issuer) |
| C | Street address and postal code in wrong formats. |
| D | Street address and postal code match. (International issuer) |
| E | AVS Error. |
| F | Address does compare and 5 digit ZIP does compare. (UK only) |
| G | Card issued by a non-US issuer that does not participate in the AVS system. |
| I | Address information not verified by international issuer. |
| M | Street address and postal code match. (International issuer) |
| N | No match on address (street) or ZIP. |
| P | Postal codes match, street address not verified due to incompatible formats. |
| R | Retry, system unavailable or timed out. |
| S | Service not supported by issuer. |
| U | Address information is unavailable. (Domestic issuer) |
| W | 9 digit ZIP matches, address (street) does not. |
| X | Exact AVS match. |
| Y | Address (street) and 5 digit ZIP match. |
| Z | 5 digit ZIP matches, address (street) does not. |
CVV2 Response Codes
| M | CVV2 match. |
| N | CVV2 no match. |
| P | Not processed. |
| S | Issuer indicates that CVV2 data should be present on the card, but the merchant has indicated that the CVV2 data is not present on the card. |
| U | Issuer has not certified for CVV2 or issuer has not provided Visa with the CVV2 encryption keys. |
Error Testing Codes
If you would like to simulate an error while testing (test=1) use the CVV2 codes below:
| 200 | Transaction amount error - please try again, or contact the merchant |
| 201 | Transaction amount over merchant limit - please contact the merchant |
| 202 | DECLINED - CVV2 mismatch, please verify value entered |
| 203 | DECLINED - credit card failed negative check, please try again with a different card |
| 204 | DECLINED - credit card declined |
| 205 | DECLINED - system busy, please try again |
| 206 | DECLINED - expired credit card |
| 207 | DECLINED - invalid credit card |
| 208 | Invalid data submitted for VOID |
| 209 | DECLINED - system busy, please try again |
| 210 | Please retry transaction |
| 211 | Invalid transaction id for void |
| 212 | Invalid request |
| 213 | Transaction error - please try again or contact the merchant for help |
AVS Response Test Codes
If you would like to simulate a particular AVS response while testing (test=1) use the CVV2 codes below (default is X):
| 001 | A |
| 002 | B |
| 003 | C |
| 004 | D |
| 005 | E |
| 006 | F |
| 007 | G |
| 008 | I |
| 009 | M |
| 010 | N |
| 011 | P |
| 012 | R |
| 013 | S |
| 014 | U |
| 015 | W |
| 016 | Y |
| 017 | Z |
CVV2 Response Test Codes
If you would like to simulate a particular CVV2 response while testing (test=1) use the CVV2 codes below (default is M):
| 100 | N |
| 101 | P |
| 102 | S |
| 103 | U |
Recurring Transactions
Recurring transactions are used when customers need to be billed repeatedly on a weekly or monthly basis. Creating a recurring transaction works very similar to regular purchases, with the addition of four recurring variables used to determine the billing schedule. The transaction type must also be changed to "recurring" in order for the gateway to identify the transaction properly.
It is important to take note that the transactions themselves, whether the initial amount or the scheduled billings, can still be voided in the same way as regular purchases.
Initial Amount (optional)
For recurring transactions the "amount" variable is no longer required and is instead optional. If no amount is sent, the customer will only be charged on the start date of the billing schedule. If an amount is provided, the customer will be billed that amount immediately.
Start Date
If the start date is after the 28th of any given month the billing cycle will fall on the last day of each month. For example, if the start date were April 30th, the next billing date would fall on May 31st, then June 30th, and so on.
Billing Schedules - Examples
Example #1 recurringPeriod = "1 month" recurringStartDate = "2008-05-31" recurringAmount = "25.00" recurringTimes = "36" The customer would be billed $25.00 every month, starting May 31st, for a total number of 36 billings. Example #2 recurringPeriod = "2 months" recurringStartDate = "2008-06-15" recurringAmount = "7.95" recurringTimes = "6" amount = "29.00" The customer would be billed $7.95 every 2 months, starting June 15th, for a total number of 6 billings, and would also be charged $29.00 immediately.
Request Variables (Recurring)
*** NOTICE: All fields are case-sensitive.
Required
| merchantId | numeric | Your merchant id; must not include any spaces or special characters. |
| token | alpha | Your Gateway token (generated within the Gateway Administration Tool). |
| type | alpha | Type of transaction to be processed. Must be: recurring. |
| cardNumber | 16/numeric | Credit card number; must not include any spaces or special characters. |
| expiryDate | 4/numeric | Credit card expiry date in the form of MMYY. With leading zeroes if the month or year is only one digit. |
| cvvIndicator | 1/numeric | CVV2 presence indicator. Must be either 1, 2 or 3 (1 = present, 2 = not visible, 3 = not present) |
| cvv | 4/numeric | CVV2 value. |
| cardholderName | 100/alpha | Name on card. |
| cardholderAddress | 255/alpha | Address of cardholder for address verification. |
| cardholderPostalCode | 50/alpha | Postal code/zip code of cardholder for address verification. |
| test | 1/numeric | Sets whether this is a test transaction or not. Any value other than 1 will assume this is a real transaction. |
| recurringPeriod | 50/alpha | Recurring period; set weekly or monthly: 1 week(s), 2 week(s), 1 month(s), 2 month(2), 6 month(s), 24 month(s) Also allows the following aliases: weekly, biweekly, monthly, bimonthly |
| recurringStartDate | yyyymmdd | The data to start recurring billing (cannot be today). |
| recurringAmount | 10,2/decimal | Amount of each recurring transaction. |
| recurringTimes | 3/numeric | Number of times to bill. |
Order Information (optional)
| amount | 10,2/decimal | If set, this is the amount the customer will be billed immediately. |
| orderId | 50/alpha | Unique transaction identifier, transaction will fail if a duplicate order id is found. The order id will be automatically generated by the Gateway if this field is blank. |
| customerId | 50/alpha | Customer identifier. |
Billing Information (optional)
| billingName | 100/alpha | Customer's billing name. |
| billingAddress | 255/alpha | Customer's billing address. |
| billingCity | 255/alpha | Customer's billing city. |
| billingProvince | 255/alpha | Customer's billing province or state. |
| billingPostalCode | 50/alpha | Customer's billing postal code or zip code. |
| billingCountry | 255/alpha | Customer's billing country. |
| billingPhoneNumber | 255/alpha | Customer's billing phone number. |
| billingEmailAddress | 255/alpha | Customer's billing email address. |
Form Sample (Recurring)
Below is an HTML form sample with all the required fields for processing a transaction as well as optional fields:
<form action="https://gateway.helcim.com/" method="POST"> <!-- Required Fields --> <input type="hidden" name="merchantId" value="<your_merchant_id>"> <input type="hidden" name="token" value="<your_gateway_token>"> <input type="hidden" name="test" value="1"> <input type="hidden" name="type" value="purchase"> <input type="hidden" name="cardholderName" value="John Doe"> <input type="hidden" name="cardNumber" value="4242424242424242"> <input type="hidden" name="expiryDate" value="0315"> <input type="hidden" name="cvvIndicator" value="1"> <input type="hidden" name="cvv" value="123"> <input type="hidden" name="cardholderAddress" value ="111 25th Ave"> <input type="hidden" name="cardholderPostalCode" value="T2S3G4"> <input type="hidden" name="recurringPeriod" value="1 month"> <input type="hidden" name="recurringStartDate" value="20090131"> <input type="hidden" name="recurringAmount" value="10.00"> <input type="hidden" name="recurringTimes" value="24"> <!-- Order Information (optional) --> <input type="hidden" name="amount" value="18.00"> <input type="hidden" name="orderId" value="invoice1"> <input type="hidden" name="customerId" value="customer1"> <!-- Billing Information (optional) --> <input type="hidden" name="billingName" value="Billing Name"> <input type="hidden" name="billingAddress" value="Billing Address"> <input type="hidden" name="billingCity" value="Billing City"> <input type="hidden" name="billingProvince" value="Billing Province"> <input type="hidden" name="billingPostalCode" value="Billing PC"> <input type="hidden" name="billingCountry" value="Billing Country"> <input type="hidden" name="billingPhoneNumber" value="Billing Phone"> <input type="hidden" name="billingEmailAddress" value="example@example.com"> <input type="submit" name="submit" value="Submit"> </form>
