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
orDECLINED
in thestatus
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 toaccept
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 theinvoiceNumber
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
: AbillingAddress
object is required for all transactions processed through the Purchase, Preauth, Verify, and Withdraw transaction endpoints. At a minimum this object requiresname
,street1
andpostalCode / 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 validcardData
object is required for all requests to the Process Purchase Transaction and Process Preauth Transaction endpoints. This object should contain eithercard
orcardToken
values, but not both. These will be used by the Helcim API to process the transactionamount
sent in the request, or verify and tokenize the card details.- The
cardData
object required for the Process Verify Transaction endpoint should containcard
values that include thecardNumber
,cardExpiry
, andcardCVV
, 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 thecustomer
object associated with that token, even without thecustomerCode
being provided in the request.
- The
bankData
: A validbankData
object is required for all requests to the Process Withdraw Transaction endpoint. This object should contain eitherbankAccount
orbankToken
values, but not both. These will be used by the Helcim API to process the withdraw transactionamount
sent in the request. A validbankToken
can be obtained from an existing customer profile in the Helcim system, andbankAccount
data sent through this endpoint will be tokenized and returned in theresponse
.
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, acustomerCode
can be passed in the request. If nocustomerCode
is passed, one will be created based on a combination ofcardData
/bankData
andbillingAddress
information.invoiceNumber
: A Purchase, Preauth, Verify or Withdraw transaction can be made against an existing invoice by passing aninvoiceNumber
in the body of the request. If noinvoiceNumber
is passed, an invoice object will be created with a status ofpaid
ordue
and linked to the respectivecustomer
object by a successful transaction.invoice
: When processing a new Purchase, Preauth, Verify or Withdraw transaction, you have the option to include aninvoice
object to determine key information to appear on the invoice created by the transaction, including theinvoiceNumber
, productlineItems
,shipping
andpickup
information, as well astax
anddiscount
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
topaid
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
: ThetransactionId
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 thetransactionId
.
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
topaid
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
, andcardCVV
details in thecardData
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
: TheoriginalTransactionId
for the purchase or capture transaction that you are looking to partially or fully refund. If you have not stored thetransactionId
in your database, then you can use the Collect Card Transactions endpoint with a combination of search parameters to locate theoriginalTransactionId
. 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
: ThecardTransactionId
for the purchase or capture transaction that you are looking to reverse. If you have not stored thetransactionId
in your database, then you can use the Collect Card Transactions endpoint with a combination of search parameters to locate thecardTransactionId
. 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.
Updated 2 months ago