Request Variables
This documentation is for the legacy Helcim Gateway. New merchants should refer to the Helcim Commerce API documentation.
Minimum Required
| Name | Type | Description |
|---|---|---|
| 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", "preauth", "capture", "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" (present), "2" (not visible), "3" (not present) or "4" (ignore) |
| cvv | 4/numeric | CVV2 value. |
Card-Tokenization Variables
This also requires the minimum required variables to be sent. This replaced cardNumber and CVV
| Name | Type | Description |
|---|---|---|
| cardToken | 23/alpha | The credit card token. Can be used for "purchase", "refund" and "preauth". When used the cardNumber, expiryDate, cvvIndicator and cvv fields should not be sent. |
| cardF4l4 | 8/numberic | The first and last four digits of the original credit card. This is used to confirm that the correct credit card will be billed. |
Capture and Void Variables
This also requires the minimum required variables to be sent.
| Name | Type | Description |
|---|---|---|
| transactionId | 10/numeric | The transaction id of the original transaction. This field should only be used for "capture" and "void". When used the cardNumber, expiryDate, cvvIndicator, cvv, cardToken and cardF4l4 fields should not be sent. |
Address Verification Service
This also requires the minimum required variables to be sent.
| Name | Type | Description |
|---|---|---|
| cardholderAddress | 255/alpha | Address of cardholder for address verification. |
| cardholderPostalCode | 50/alpha | Postal code/zip code of cardholder for address verification. |
Optional Variables
This also requires the minimum required variables to be sent.
| Name | Type | Description |
|---|---|---|
| test | 1/numeric | Sets whether this is a test or not. Any value other than 1 will assume this is a real transaction. |
| cardholderName | 100/alpha | Name on card. |
| 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 (used for emailing a receipt to customer if feature is enabled) |
| 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
For all item variables replace "#" with a unique item number (1 or higher).
| Name | Type | Description |
|---|---|---|
| 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. |
| allowZeroAmount | 1/numberic | Allows a zero-dollar transaction to be processed so that a card-token can be generated. |
| transactionIndicator | 1/numberic | *Only use when sending a recurring card-token payment using your internal recurring system. Value should be set to 2. |