Unauthorized: You have attempted a request with an invalid or inactive API token. Confirm your API token is correct and active, in the Integrations section of your Helcim account, then attempt your request again. For more information on creating or checking an API token, visit our documentation here.
No access permission: You have attempted a request that requires permissions that the API token passed in the request is not allowed to complete. Update your token permissions in the Integrations section of your Helcim account and attempt your request again. For more information on configuring API permissions, visit our documentation here.
Helcim API
Payment API
Error Message
Status
Description
Failed to process transaction
500
You have attempted to process a credit card transaction using a cardToken that is not associated with the API token, Helcim account, or customerCode that you have passed in your request. Check your Customer section in your Helcim account to confirm that the cardToken is correct before attempting your request again. Helcim developer test accounts are unable to process test ACH transactions and this error will be returned if attempted.
Not allowed to send full card number
401
You have attempted to process a transaction using a full card number and are not approved to do so. Utilize HelcimPay.js or Helcim.js to tokenize card details and send a cardToken in the cardData object instead of the card details.
Missing required cardData
400
When a request is sent to the Payment API and a required card or cardToken object is missing, the API will respond with a "Missing required data" error object. Please note that if neither potential cardData object is provided, the API will respond to indicate that the cardNumber, cardExpiry, and cardCVV are missing, even if not approved for full card numbers. Please send either a card object or cardToken to resolve this error based on your accounts approval for sending full card numbers.
Missing required data
400
The Helcim API will respond with a "Missing required data" error when a data object required for your request is missed. In addition to cardData as outlined above, this error can be triggered by a range of required data objects being missing from your request. The errors object will outline what data object is missing.
Missing idempotency key
400
You have attempted to process a transaction without sending a valid idempotency key with your request. Generate a new idempotency-key and send this in the header of your request before attempting your request again. Go to our article on Idempotency keys for more information on how to generate these.
Failed to retrieve card transaction
400
When attempting to capture, refund, or reverse a transaction, the Helcim API will return a "Failed to retrieve card transaction" error, if the transactionId does not match any transaction in your Helcim account. Check your transactionId is correct through your Helcim account, or the Card Transaction API before attempting your request again.
Disabled achSetting
401
If you attempt to send a request to the Process Withdraw Transaction endpoint and your account does not have ACH Bank Payments enabled, the API will return an error response of Disabled achSetting. To resolve this error, log into your Helcim account and go to Settings, then ACH Bank Payment Settings, in order to toggle on "Enable ACH Bank Payments" for your Helcim account. Please note that some accounts are restricted from processing through ACH entirely and you should review our Acceptable Use Policy if this setting is not available for you.
Card Batch API
Error Message
Status
Description
Card batch not found
404
The Get Card Batches API endpoint will respond with a "Card batch not found" error if a specific batchNumber and / or terminalId provided in the request cannot be found in your Helcim account. Check your batchNumber or terminalId is valid through your Helcim account before attempting your request again. Please note that the batchNumber and the cardBatchId are not the same.
Failed to retrieve card batch with ID
500
The Get Card Batch API endpoint will respond with a "Failed to retrieve card batch with ID" error if the cardBatchId passed in the request cannot be found in your Helcim account. Check your cardBatchId is correct before attempting your request again. Please note that the batchNumber and the cardBatchId are not the same.
Card batch already closed
400
The Settle an Open Card Batch API endpoint will respond with a "Card batch already closed" error if the passed cardBatchId belongs to an already settled card batch. No further action is required.
Card Transaction API
Error Message
Status
Description
Empty response
200
The Card Transaction API will respond with an empty array if the query params used in the request do not locate any transactions that meet the filtering criteria.
Failed to retrieve card transaction
400
The Get Card Transaction by id API endpoint will respond with a "Failed to retrieve card transaction" error if a specific cardTransactionId provided in the request cannot be found in your Helcim account. Confirm the transactionId is correct through your Helcim account, before attempting your request again
Customer API
Error Message
Status
Description
Customer does not exist
404
The Get customers API endpoint will return an error of "Customer does not exist" if the customerCode or search params included in the request cannot locate data in your Helcim account that matches your request. Confirm the correct values are being passed before attempting your request again.
Customer not found
404
The Get customer, Update customer, and Get customer cards API endpoints will return an error of "Customer not found" if the customerId value passed in your request cannot be located in your Helcim account. Confirm the customerId number is correct through your Helcim account, before attempting your request again. Please note that the customerCode and customerId are not the same values.
Missing required data
400
The Create customer API endpoint will respond with a "Missing required data" error when a data object required for your request is missed. This error can be triggered by a range of required data objects being missing from your request. The errors object will outline what data object is missing.
Empty response
404
The Get customer card API endpoint will respond with an empty array if the cardId value does not locate card details for the customerId provided in the request. Confirm the cardId is correct through your Helcim account before attempting the request again.
Invoice API
Error Message
Status
Description
Empty response
404
The Get invoices API endpoint will respond with an empty array if the query parameters provided in the request do not locate any matching Invoice data in your Helcim account. Confirm your query parameters are correct before attempting your request again.
Invoice number already existed
400
The Create invoice API endpoint will respond with an "Invoice number already existed" error message if the invoiceNumber provided in the request already exists in your Helcim account. Please change your invoice number before trying the request again.
Missing required data
400
The Create invoice API endpoint will respond with a "Missing required data" error message when a data object required for your request is missed. This error can be triggered by a range of required data objects being missing from your request and the errors object will outline what data object is missing. Include the missing required data before trying the request again.
Invalid line items
400
The Create invoice API endpoint requires you to provide valid line items in the form of an array of objects. If no lineItems are provided in the request you will receive an "Invalid line items" response from the API. Add your line items before attempting your request again.
