The Payment API allows you to process credit card payments online, through your existing website or application. Payment types include Purchase, Preauthorization, Capture, Verify, Refund, Reverse, and ACH Withdraw.

A successful payment processed through the Payment API will create a transaction object in the Helcim system. Where an existing customerCode or invoiceNumber was not associated with the payment, new ones will be created and returned in the response.

Payment API Endpoints

Review the following documentation for specific payment methods available through the Payment API.

• Process a credit card payment
• Preauthorize a credit card payment
• Capture a credit card payment
• Reverse a credit card payment
• Refund a credit card payment
• Verify credit card details

Payment API Functionality

Idempotency

The Payment API endpoints require an idempotency key be sent in the header of your requests. These allow you to retry requests is you lose connection, while safely avoiding duplicate transactions.

What is an Idempotency Key?

An idempotency key is sent in the header of a Payment API request, to ensure that a transaction is only processed once. This helps to avoid duplicate transactions should you need to resubmit a request if your connection fails before receiving a response from the Helcim system.

Sending this key allows you to confidently re-submit any transaction requests through the Helcim Payment API and it will return the response of the initial transaction request rather than processing a subsequent transaction.

How Idempotency Works in the Payment API

Idempotency keys submitted to the Payment API are cleared after 5 minutes, ensuring you have the opportunity to attempt transactions a second time. A submitted idempotency key will be associated with the specific transaction that it was originally sent with until they are cleared and cannot be reused until then.

The Helcim API will first check to see if the passed idempotency key exists in our system.

• If the idempotency key does not exist in our system, the Payment API will process the transaction request.
• If the idempotency key does exist and the payload sent in the request is identical to the previous payload received for that key, then Payment API will return the response from the first successful request.
• If the idempotency key does exist and the payload sent in the request is different from the previous payload received for that key, then the Payment API will return a 409 status code and an error object due to the same key being used.
• If the idempotency key does not exist in our system, but the payload of the request is identical to a previous payload received in the last 5 minutes, the Suspected Duplicate check will be triggered.

Recommended Functions for Creating Idempotency Keys

You can submit any alphanumeric value for your idempotency key, but they need to be 25 characters long and must be unique. The generation and tracking of idempotency keys used for transactions will remain the merchants responsibility.

We recommend the following UUID functions for generating keys, however please note that because UUID generates a 36 character string, you will need to slice the string generated before passing this in your request.

Suspected Duplicate Transactions

In order to protect Helcim merchants against accidental duplicate transactions, the Helcim system has functionality built in that will automatically decline transactions that are potentially duplicates. This check was put in place to avoid duplicate transactions processed through Helcim services like the Virtual Terminal, the Helcim App, and the Helcim API.

How does the Suspected Duplicate Check Work?

The suspected duplicates process is a secondary process to Idempotency Keys. This check will trigger even in instances where the flagged duplicate transaction has a different idempotency key from the original transaction.

The Suspected Duplicate check will review any successful transactions within 5 minutes where the cardNumber, cardholderName, and amount match a previous transaction within that time period.

Suspected duplicate transactions will have a transaction status of "DECLINED" returned in the transaction response object, with an errors message stating "Transaction Declined: DECLINED - Suspected duplicate transaction in the last 5 minutes.".

// Example payment declined due to failing suspected duplicate check

{
	"transactionId": 21071575,
  "dateCreated": "2024-07-13 16:07:54",
  "cardBatchId": 0,
  "status": "DECLINED",
  "user": "Helcim System",
  "type": "purchase",
  "amount": 10.99,
  "currency": "USD",
  "avsResponse": "",
  "cvvResponse": "",
  "errors": "Transaction Declined: DECLINED - Suspected duplicate transaction in the last 5 minutes."
}

Processing Terminals

What is a Processing Terminal?

A terminal is what communicates credit card transaction data between the Helcim system and the card networks and issuing banks. It holds certain settings such as the processor network, currencies, settlement times and other card processing configurations.

All transactions processed through the Helcim system will eventually go through the merchants processing terminal regardless of where that transaction originated.

Where Can I Find My Terminal Information?

Login to your Helcim account, and under the All Tools menu, select Payments, and click on Terminals. You will see a list of all the terminals available and their currency.

The Helcim API will process on the default terminal for your account.

📘

By clicking on a specific terminal, you will be able to view its unique ID.

Processing with Multiple Currencies

For Canadian based merchants who are set up to accept both CAD and USD currencies, you can determine the currency and terminal to be processed on by sending the relevant currency value with your payment request.

📘

API Default Behavior

If you have both a CAD and USD processing terminal on your account, the Helcim system will process on the relevant terminal based on the currency passed in the request.