Request Variables
  • 29 Aug 2022
  • 4 Minutes to read
  • Contributors
  • Dark
    Light

Request Variables

  • Dark
    Light

Minimum Required

NameTypeDescription
merchantIdnumericYour merchant id; must not include any spaces or special characters.
tokenalphaYour Gateway token (generated within the Gateway Administration Tool).
typealphaType of transaction to be processed. Must be either: "purchase", "preauth", "capture", "refund" or "void".
amount10,2/decimalAmount to process. Must include two decimal places, and must NOT include $.
cardNumber16/numericCredit card number; must not include any spaces or special characters.
expiryDate4/numericCredit card expiry date in the form of MMYY. With leading zeroes if the month or year is only one digit.
cvvIndicator1/numericCVV2 presence indicator. Must be either: "1" (present), "2" (not visible), "3" (not present) or "4" (ignore)
cvv4/numericCVV2 value.

Card-Tokenization Variables

This also requires the minimum required variables to be sent. This replaced cardNumber and CVV

NameTypeDescription
cardToken23/alphaThe credit card token. Can be used for "purchase", "refund" and "preauth". When used the cardNumber, expiryDate, cvvIndicator and cvv fields should not be sent.
cardF4l48/numbericThe 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.

NameTypeDescription
transactionId10/numericThe 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.

NameTypeDescription
cardholderAddress255/alphaAddress of cardholder for address verification.
cardholderPostalCode50/alphaPostal code/zip code of cardholder for address verification.

Optional Variables

This also requires the minimum required variables to be sent.

NameTypeDescription
test1/numericSets whether this is a test or not. Any value other than 1 will assume this is a real transaction.
cardholderName100/alphaName on card.
billingName100/alphaCustomer's billing name.
billingAddress255/alphaCustomer's billing address.
billingCity255/alphaCustomer's billing city.
billingProvince255/alphaCustomer's billing province or state.
billingPostalCode50/alphaCustomer's billing postal code or zip code.
billingCountry255/alphaCustomer's billing country.
billingPhoneNumber255/alphaCustomer's billing phone number.
billingEmailAddress255/alphaCustomer's billing email address (used for emailing a receipt to customer if feature is enabled)
Shipping Information
shippingName100/alphaCustomer's shipping name.
shippingAddress255/alphaCustomer's shipping address.
shippingCity255/alphaCustomer's shipping city.
shippingProvince255/alphaCustomer's shipping province or state.
shippingPostalCode50/alphaCustomer's shipping postal code or zip code.
shippingCountry255/alphaCustomer's shipping country.
shippingPhoneNumber255/alphaCustomer's shipping phone number.
shippingEmailAddress255/alphaCustomer's shipping email address.

Order Information

For all item variables replace "#" with a unique item number (1 or higher).

NameTypeDescription
orderId50/alphaUnique 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.
customerId50/alphaCustomer identifier.
commentsalphaAny extra information from the cardholder or merchant.
itemId#50/alphaItem SKU.
itemDescription#255/alphaItem description.
itemQuantity#4,2/decimalItem quantity, must be at least one for item to be added.
itemPrice#10,2/decimalItem price per each.
itemTotal#10,2/decimalItem price X quantity.
shippingAmount10,2/decimalTotal shipping amount.
taxAmount10,2/decimalTotal tax amount.
allowZeroAmount1/numbericAllows a zero-dollar transaction to be processed so that a card-token can be generated.
transactionIndicator1/numberic*Only use when sending a recurring card-token payment using your internal recurring system. Value should be set to 2.

Code Samples

Minimal 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="type" value="purchase">
<input type="hidden" name="amount" value="10.00">
<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="submit" name="submit" value="Submit">
</form>

Using Card Tokenization

<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="type" value="purchase">
<input type="hidden" name="amount" value="10.00">
<input type="hidden" name="cardToken" value="ah298ajjk2981772hjj2909">
<input type="hidden" name="cardF4l4" value="42424242">
<input type="hidden" name="cvvIndicator" value="4">
<input type="submit" name="submit" value="Submit">
</form>

Using 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="type" value="purchase">
<input type="hidden" name="amount" value="18.00">
<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">

<!-- Optional Fields -->
<input type="hidden" name="test" value="1">
<input type="hidden" name="cardholderName" value="John Doe">
<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="orderId" value="order1">
<input type="hidden" name="comments" value="Order comments.">

<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="shippingAmount" value="1.00">
<input type="hidden" name="taxAmount" value="2.00">

<input type="submit" name="submit" value="Submit">
</form>

Recurring Transaction

<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="recurring">
<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="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">
<input type="hidden" name="cardholderName" value="John Doe">
<input type="hidden" name="cardholderAddress" value ="111 25th Ave">
<input type="hidden" name="cardholderPostalCode" value="T2S3G4">

<!-- 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>