Payment API

The Payment API endpoints enable merchants to process credit card or ACH withdrawal payments through their website or application. Payment types include Purchase, Preauthorization, Capture, Verify, Refund, Reverse, and Withdraw.

The following documentation will provide more information on the required header and body parameters for these requests, as well as outline any nuances that developers should be aware of for specific endpoints.

🚧
Payment API Responses:
A 200 response status being received does not indicate that a purchase, preauthorization, or verify transaction was approved, as a declined transaction is still a successful API action and response.
The outcome of the transaction will be returned as APPROVED or DECLINED in the status value of the transaction response object.

Required Header Parameters

api-token: All Payment API endpoints require a valid 'api-token' to be sent in the header of the request to authenticate with the API, in addition to accept and 'content-type'values set to 'application/json'.

'idempotency-key': In addition to the header parameters required for all Helcim API requests, the Payment API endpoints also require an 'idempotency-key' value be passed in the header of the request to protect against duplicate transactions should you lose connection before receiving a response from the API.

Review our documentation for information on Idempotency Keys and how to implement these in your integration.

Required Body Parameters

ipAddress: The Helcim system has additional fraud protection processes to protect our merchants against fraudulent transactions. Sending the IP address of the customer processing the transaction is used as part of this protection and is required for all Payment API endpoints. Where the payment type would be merchant initiated, such as a Reverse, Refund, or Capture Transactions, then the user IP address of the original transaction can be passed in the request.
currency: The currency for any Purchase, Preauth, Verify or Withdraw transaction should be the default currency of your processing terminal. The currency must match any existing invoices linked to the transaction through the invoiceNumber field.
- For Credit Card transactions, Canadian merchants can process in both CAD and USD, whereas US merchants may only process in USD.
- For ACH Bank transactions, merchants may only process transactions in the local currency for their Helcim account.
- For more information on enabling multiple currencies, visit our Multiple Currencies documentation.
amount: The amount to be processed in the transaction should be passed in any requests.
- For the Process Purchase Transaction and Process Preauth Transaction endpoints, the amount must be a value greater than 0. There is no upper transaction limit on amounts for credit card processing through the Helcim API. These limits are governed and enforced by issuing banks on a card by card basis and surpassing this limit will result in a declined transaction.
- For the Process Capture Transaction endpoint, the amount must be a value greater than 0 but cannot exceed the amount of the original Preauth Transaction being captured.
- For the Process Refund Transaction endpoint, the amount to be refunded should be passed in the request and must be a value greater than 0 but less than the original transaction amount. You cannot refund an amount that exceeds the original transaction being refunded.
billingAddress: A billingAddress object is required for all transactions processed through the Purchase, Preauth, Verify, and Withdraw transaction endpoints. At a minimum this object requires name, street1 and postalCode / zipCode values to be included in the object. This data is used by the Helcim API for creation of customer, invoice and transaction objects in the Helcim system.
cardData: A valid cardData object is required for all requests to the Process Purchase Transaction and Process Preauth Transaction endpoints. This object should contain either card or cardToken values, but not both. These will be used by the Helcim API to process the transaction amount sent in the request, or verify and tokenize the card details.
- The cardData object required for the Process Verify Transaction endpoint should contain card values that include the cardNumber, cardExpiry, and cardCVV, therefore you should be approved to process full card numbers in order to use this endpoint. These details will be used by the Helcim API to verify and tokenize the card details sent in the request.
- If you are not approved to send full card numbers you should always send a cardToken in this object, obtained by verifying and tokenizing the card details through HelcimPay.js or Helcim.js.
- Transactions processed with an existing cardToken will be automatically linked to the customer object associated with that token, even without the customerCode being provided in the request.
bankData: A valid bankData object is required for all requests to the Process Withdraw Transaction endpoint. This object should contain either bankAccount or bankToken values, but not both. These will be used by the Helcim API to process the withdraw transaction amount sent in the request. A valid bankToken can be obtained from an existing customer profile in the Helcim system, and bankAccount data sent through this endpoint will be tokenized and returned in the response.

Optional Body Parameters

Helcim Payment API endpoints will accept a range of optional body parameters in their request to allow for additional functionality when processing transactions through the API.

customerCode: In order to link a new Purchase, Preauth, Verify or Withdraw transaction to an existing customer in the Helcim system, a customerCode can be passed in the request. If no customerCode is passed, one will be created based on a combination of cardData / bankData and billingAddress information.
invoiceNumber: A Purchase, Preauth, Verify or Withdraw transaction can be made against an existing invoice by passing an invoiceNumber in the body of the request. If no invoiceNumber is passed, an invoice object will be created with a status of paid or due and linked to the respective customer object by a successful transaction.
invoice: When processing a new Purchase, Preauth, Verify or Withdraw transaction, you have the option to include an invoice object to determine key information to appear on the invoice created by the transaction, including the invoiceNumber, product lineItems, shipping and pickup information, as well as tax and discount details.

Payment API Endpoints

Purchase Transaction

The Purchase Transaction endpoint can be used to create a new Credit Card Payment through the Helcim API. This endpoint will accept a combination of header and body params and return a response indicating the outcome of the transaction.

Transaction Flow

Utilize HelcimPay.js or Helcim.js to verify and tokenize the customer card details.
Store the returned cardToken in your database.
Use the cardToken to process the transaction through the Process Purchase Transaction endpoint.
Store the response in your database.

Pre-Authorization Transaction

The Preauth Transaction endpoint can be used to preauthorize a Credit Card Payment through the Helcim API to be partially or fully captured at a later point. This endpoint will accept a combination of header and body params and return a response indicating the outcome of the transaction.

🚧
Capture Timeframes:
Preauthorized transactions must be captured within 7 days of processing, or they will automatically expire.

Transaction Flow

Utilize HelcimPay.js or Helcim.js to verify and tokenize the customer card details.
Store the respective card token in your database.
Use the cardToken to process the transaction through the Process Preauth Transaction endpoint.
Store the returned details, including the preAuthTransactionId, in your database to process your Capture transaction.
When ready to capture a preauthorized transaction, call the Process Capture Transaction endpoint. The associated invoice will be updated from due to paid at this time.

Capture Transaction

The Capture Transaction endpoint can be used to capture part or all of a preauthorized Credit Card Payment processed through the Helcim API. This endpoint will accept a combination of header and body params and return a response indicating the outcome of the transaction.

Required Body Parameters

preAuthTransactionId: The transactionId for the original preauthorized transaction. If you have not stored preauthorized transactions in your database, then you can use the Collect Card Transactions endpoint with a combination of search parameters to locate the transactionId.

Transaction Flow

Fetch the preAuthTransactionId and preauth amount from your database
Use the preAuthTransactionId and to process and capture a partial or full amount of the transaction through the Process Capture Transaction endpoint. The associated invoice will be updated from due to paid at this time.

Verify Transaction

The Verify Transaction endpoint can be used by merchants who are approved for sending full card numbers, to process a $0 verify transaction and tokenize Credit Card details through the Helcim API. This endpoint will accept a combination of header and body params and return a response indicating the outcome of the transaction.

📘
Request Requirements:
The Process Verify Transaction endpoint only accepts full card numbers, so you need to be approved to process in full card numbers in order to use this endpoint.
If you are not approved to send full card numbers through the API, we recommend using HelcimPay.js or Helcim.js to verify and tokenize card details and then process payments through the Process Purchase Transaction using the cardToken returned in the response object of this endpoint.

Transaction Flow

Use the customer provided card details to call the Process Verify Transaction endpoint.
Send the cardNumber, cardExpiry, and cardCVV details in the cardData object included in the body of your request.
Send the required billing information in the billingAddress object in the body of your request and send this to the Process Verify Transaction endpoint.
Save the returned response and cardToken in your database for later use in the Process Purchase Transaction API endpoint.

Refund Transaction

The Refund Transaction endpoint can be used by merchants to process a partial or full refund for previous transactions processed through the Helcim system. This endpoint will accept a combination of header and body params and return a response indicating the outcome of the transaction.

📘
Request Requirements:
In order to process a Refund Transaction, the original transaction must be in a closed batch. If the batch of the transaction remains open, you should use the Process Reverse Transaction endpoint.

Required Body Parameters

originalTransactionId: The originalTransactionId for the purchase or capture transaction that you are looking to partially or fully refund. If you have not stored the transactionId in your database, then you can use the Collect Card Transactions endpoint with a combination of search parameters to locate the originalTransactionId. All refunds should be related to an original transactions processed through the Helcim system and you cannot process standalone refunds through the Helcim API.

Transaction Flow

Access the originalTransactionId from your database or the Collect Card Transactions endpoint.
Send the required information in the request, including the amount of the refund to be processed, to the Process Refund Transaction endpoint.
Save the returned response in your database if required.

Reverse Transaction

The Reverse Transaction endpoint can be used by merchants to process full reversal or void of previous transaction processed through the Helcim system. This endpoint will accept a combination of header and body params and return a responseMessage indicating the outcome of the transaction.

📘
Request Requirements:
In order to process a Reverse Transaction, the transaction being reversed must be in an open batch. If the batch of the transaction has closed, you must use the Process Refund Transaction endpoint.

Required Body Parameters

cardTransactionId: The cardTransactionId for the purchase or capture transaction that you are looking to reverse. If you have not stored the transactionId in your database, then you can use the Collect Card Transactions endpoint with a combination of search parameters to locate the cardTransactionId. All reverses should be related to an original transactions processed through the Helcim system and you cannot process a reverse for a transaction that is in a closed batch.

Transaction Flow

Access the cardTransactionId from your database or the Collect Card Transactions endpoint.
Send the required information in the request for the transaction you wish to reverse, to the Process Reverse Transaction endpoint.
Save the returned response in your database if required.

Withdraw Transaction

The Withdraw Transaction endpoint can be used by merchants to process an ACH / bank transactions through the Helcim system. This endpoint will accept a combination of header and body params and return a response indicating the outcome of the transaction.

📘
Important Notes:
In order to process a Withdraw Transaction through the Helcim API:

The merchant must ensure that the customer has accepted a preauthorized debit agreement and that those are stored and accessible for any disputes. Attempting to process a Withdraw Transaction without an approved and valid PAD agreement, will result in the customers bank rejecting the payment.

ACH Bank Payments must be enabled in the Settings section of their Helcim account under ACH Bank Payment Settings.

Certain industries are restricted from processing ACH transactions through the Helcim system. Please review our Acceptable Use Policy for more information.

Body Parameters

For a comprehensive list of the required and optional body parameters for this request, as well as being able to test requests and responses in the language you use, please review our API Reference documentation for the Process Withdraw Transaction endpoint.

Transaction Flow

Obtain a PAD agreement from your customer and store this in your records.
Send the bankData and required fields to process the transaction through the Process Withdraw Transaction endpoint.
Store the response in your database.