Helcim Logo Support & Tutorials

© Copyright 2006-2018 Helcim Inc.

All Rights Reserved.

Helcim Commerce API » Processing Payments » Card Payments »

Pre-Authorization (Preauth)

This API call let's you process a preauthorization. The response is an XML of the processed preauthorization.

Request Fields

Field Name Type Required Description
transactionType String Yes preauth
accountId Integer Yes The Helcim Commerce account ID.
apiToken String Yes API token used for authentication and access control. 
amount Decimal Yes The amount of the transaction.
cardHolderName String No The cardholder names.
cardNumber Integer Yes The credit card number.
cardExpiry Integer Yes The credit card expiration date
cardCVV Integer No The credit card CVV (digits on back of credit card).
cardHolderAddress String No The card holder's address.
cardHolderPostalCode String No The card holder's postal code.
orderNumber String No The order number.
comments String No Optional comments.
billing_contactName String No The billing contact name.
billing_businessName String No The billing business name.
billing_street1 String No The billing street address.
billing_street2 String No The billing street address.
billing_city String No The billing city.
billing_province String No The billing province.
billing_country String No The billing country.
billing_postalCode String No The billing postal code.
billing_phone String No The billing phone number.
billing_fax String No The billing fax number.
billing_email String No The billing email address.
shipping_contactName String No The shipping contact name.
shipping_businessName String No The shipping business name.
shipping_street1 String No The shipping street address.
shipping_street2 String No The shipping street address.
shipping_city String No The shipping city.
shipping_province String No The shipping province.
shipping_country String No The shipping country.
shipping_postalCode String No The shipping postal code.
shipping_phone String No The shipping phone number.
shipping_fax String No The shipping fax number.
shipping_email String No The shipping email address.
amountShipping Decimal No The shipping cost.
amountTax Decimal No The total tax amount.
shippingMethod String No The shipping method.
taxDetails String No The tax name.
itemSKU# Integer No The sku. NOTICE: For all item variables replace "#" with a unique item number (starting at 1, and increasing by 1 for each unique item added).
itemDescription# String No The item description.
itemSerialNumber# String No The item serial number.
itemQuantity# Decimal No Item quantity, must be at least one for item to be added.
itemPrice# Decimal No The item price.
itemTotal# Decimal No The item price multiplied by the quantity.

Response Fields (XML)

Field Name Type Description
message - XML structure
response Integer 1 or 0. Whether the transaction was approved or declined.
responseMessage String Result of transaction (Approved/Denied).
notice String Error/warning message from Helcim. 
transaction - XML structure
transactionId Integer The transaction ID.
type String The transaction type (purchase, refund, pre-auth, capture).
date String The date of the transactions
time String The time of the transaction.
cardHolderName String The card holder's name.
amount Decimal The amount of the transactions.
currency String The currency of the transaction.
cardnumber String The credit card number (first 4 and last 4 digits only).
cardToken String The credit card token.
expiryDate Integer The credit card expiry date.
cardType String The credit card type (Visa, Mastercard, Amex, Discovery).
avsResponse String The address verification response.
cvvResponse String The CVV verification response.
approvalCode String The approval code.
orderNumber String The order number.
customerCode String The customer code.

Errors

For all API requests, there are also generic API authentication and user access restriction errors.
Response Code Error Code Message Description
0 - Invalid Amount The transaction amount was not entered.
0 - Declined - Invalid Card Number Invalid Expiry Date The credit card number and/or expiry date was not entered or is invalid.

Code Samples

Sample Transaction Type Preauth Response XML

<?xml version="1.0"?>
<message>
    <response>1</response>
    <responseMessage>APPROVED</responseMessage>
    <notice></notice>
    <transaction>
        <transactionId>122929</transactionId>
        <type>preauth</type>
        <date>2017-07-07</date>
        <time>10:23:20</time>
        <cardHolderName>John Smith</cardHolderName>
        <amount>45.00</amount>
        <currency>CAD</currency>
        <cardNumber>5454********5454</cardNumber>
        <cardToken>4f3a1feab9468e7774af54</cardToken>
        <expiryDate>1019</expiryDate>
        <cardType>MasterCard</cardType>
        <avsResponse>X</avsResponse>
        <cvvResponse>M</cvvResponse>
        <approvalCode>T2E4ST</approvalCode>
        <orderNumber>Test11</orderNumber>
        <customerCode>12A1187</customerCode>
    </transaction>
</message>

HTML Form Sample Code

<input type="hidden" name="accountId" value="YOUR-ACCOUNT-ID">
<input type="hidden" name="apiToken" value="YOUR-API-TOKEN">
<input type="hidden" name="transactionType" value="preauth">
<input type="hidden" name="amount" value="12.99">
<input type="hidden" name="cardHolderName" value="John Smith">
<input type="hidden" name="cardNumber" value="5454545454545454">
<input type="hidden" name="cardExpiry" value="1020">
<input type="hidden" name="cardCVV" value="100">
<input type="hidden" name="cardHolderAddress" value="123 Home Street, Calgary, Alberta, Canada">
<input type="hidden" name="cardHolderPostalCode" value="T2H1K7">
<input type="hidden" name="orderNumber" value="ORDR11729">
<input type="hidden" name="comments" value="Premium Product">
<input type="hidden" id="billing_contactName" value="Jane Smith">
<input type="hidden" id="billing_businessName" value="ABC Business">
<input type="hidden" id="billing_street1" value="303 Avenue North">
<input type="hidden" id="billing_street2" value="Unit 1403">
<input type="hidden" id="billing_city" value="Calgary">
<input type="hidden" id="billing_province" value="Alberta">
<input type="hidden" id="billing_country" value="Canada">
<input type="hidden" id="billing_postalCode" value="T2H 1K7">
<input type="hidden" id="billing_phone" value="403-555-1234">
<input type="hidden" id="billing_fax" value="403-555-2233">
<input type="hidden" id="billing_email" value="jane@example.com">
<input type="hidden" id="shipping_contactName" value="John Smith">
<input type="hidden" id="shipping_businessName" value="ABC Business USA">
<input type="hidden" id="shipping_street1" value="400 Street West">
<input type="hidden" id="shipping_street2" value="Unit 12">
<input type="hidden" id="shipping_city" value="Seattle">
<input type="hidden" id="shipping_province" value="WA">
<input type="hidden" id="shipping_country" value="USA">
<input type="hidden" id="shipping_postalCode" value="90221">
<input type="hidden" id="shipping_phone" value="814-555-1233">
<input type="hidden" id="shipping_fax" value="814-555-6633">
<input type="hidden" id="shipping_email" value="john@example.com">
<input type="hidden" name="amountShipping" value="4.95">
<input type="hidden" name="amountTax" value="1.50">
<input type="hidden" name="shippingMethod" value="UPS">
<input type="hidden" name="taxDetails" value="10% Tax">
<input type="hidden" id="itemSKU1" value="SKU123">
<input type="hidden" id="itemDescription1" value="The First Item">
<input type="hidden" id="itemSerialNumber1" value="SN109102991">
<input type="hidden" id="itemQuantity1" value="2.00">
<input type="hidden" id="itemPrice1" value="5.00">
<input type="hidden" id="itemTotal1" value="10.00">