Payments

The payment transaction object

A transaction object is created as the result of a credit card payment attempt and is the primary means through which you will charge your customers for goods and services through the Helcim API.

A transaction stores a number of core details about a payment, including:

• Unique transactionId and cardBatchId values to manage the payment and it's associated credit card batch.
• Information about the type, amount, status, and currency of the payment.
• Information about the card type used to process the payment, the first 6 and last 4 digits of the card number, the cardholder name, and the unique cardToken for the card object created by the payment.
• The customerCode and invoiceNumber for the customer and invoice objects associated with the payment, as well as the user that processed the payment.
• The unique approval code, and AVS or CVV response values from the issuing bank.

// Example card transaction object

  {
    "transactionId": 30537777,
    "dateCreated": "2024-12-05 04:35:29",
    "cardBatchId": 4209764,
    "status": "APPROVAL",
    "user": "Helcim System",
    "type": "purchase",
    "amount": 52.5,
    "currency": "CAD",
    "avsResponse": "X",
    "cvvResponse": "",
    "cardType": "MC",
    "approvalCode": "T5E8ST",
    "cardToken": "",
    "cardNumber": "3852003237",
    "cardHolderName": "John Smith",
    "customerCode": "CST1000",
    "invoiceNumber": "INV1788",
    "warning": ""
  }

Payment types

The Payment API contains a range of endpoints that would allow you to process different payment types for your customers.

You can integrate with one or more of the Payment API endpoints. Which endpoints you use is determined by the payment behaviour you're looking to implement within your integration.

📘

ACH bank payments

A transaction object created as the result of an ACH bank payment will differ from a credit card transaction. It has a number of unique parameters within the object related to ACH bank payments.

• Review our V2.2 ACH Payment API documentation to learn more..

Refunding and reversing payments

The refund and reverse payment types can be used to return funding to a customers card, or to stop a pending payment from going through settlement. Where possible, we encourage merchants to reverse payments to avoid processing fees.

Processing refunds

• A refund payment can only be processed for payments that are in a closed card batch. Payments in a closed card batch have begun or completed the settlement process with the customers issuing bank.
• A refund payment can be for either a partial amount or full amount of the original payment.
• While there is no cost for the refund itself, because the settlement process has been actioned on the original payment the processing fees for that payment are valid and applied.

Processing reverses

• A reverse payment can only be processed for payments that are in an open card batch. Payments in an open card batch are still pending and have not begun the settlement process with the customers issuing bank.
• A reverse payment can only be for the full amount of the original payment.
• Where only a partial return is required, we recommend a reverse and then recharging the correct amount to the customer, however you may also settle the open card batch in order to complete a refund instead.
• A payment that has been reversed will not go through settlement and will typically fall off a customers statement within a few business days.

📘

Card batches and card terminals

Learn more about card batches and card terminals and how they function in the Helcim system, by reviewing the following documentation.

• Card batches
• Card terminals

Payment card data

All requests to the Purchase, Preauth, and Verify endpoints require a cardData object to be passed in the body of the request that represents the customers payment details to be used to process the payment.

For the Purchase and Preauth endpoints, the cardData object may contain either:

• A valid cardToken
• A valid cardNumber, cardExpiry, and cardCVV

For the Verify endpoint, the cardData object must contain:

• A valid cardNumber, cardExpiry, and cardCVV

❗️

By default the Payment API restricts processing with full card numbers

Review our Understanding PCI compliance documentation to better understand how to reduce the PCI scope of your integration by processing with card tokens.

• Understanding PCI compliance.

Processing with card tokens

Reducing your PCI compliance scope and risk is as simple as integrating with HelcimPay.js to process online payments, or verify and tokenize credit card details. All payments processed through HelcimPay.js will create a cardToken that can be used through our Payment API.

• Overview of HelcimPay.js.
• Processing with card tokens.

Processing with full card numbers

Integrators with the Helcim API cannot send full card numbers, expiry dates, or CVV numbers through the Payment API by default. The Payment API will return an error for any attempts to do so without approval. If your integration relies on processing with full card numbers, then review the following documentation to learn more about this approval process.

• Processing with full card numbers.

Payment status

Successful payment requests to Payment API endpoints will create a transaction object in the Helcim system with a status value of "APPROVAL" or "DECLINED".

• A payment with a status of "APPROVAL" was successfully charged. The transaction will go through settlement after the closure of the card batch the payment is included in, with the action occurring during settlement being determined by the payment type that was processed.
• A payment with a status of "DECLINED" was unsuccessful. The transaction object will contain an errors attribute with more information on the reason for the decline provided by the issuing bank.

The outcome and subsequent status of a payment attempt is determined by a combination of factors within the payments ecosystem, between Helcim, our acquiring bank, the card networks, and the customers issuing bank.

Linking invoices and customers to payments

Payments processed through the Payment API can be linked to existing customers or invoices in the Helcim system by using the customerCode and invoiceNumber parameters in your request.

• If both a customer and invoice are being linked to a payment, the customer and invoice must also associated to one another.
• If no customer and / or invoice are being linked to a payment, the Helcim system will create one using your default customer and invoice settings and return the customerCode and invoiceNumber in the API response.

In order to create a customer or invoice object in advance, you can utilize the Customer and Invoice API in order to do so.

• Create customer
• Create invoice

Instead of creating invoices in advance, the Purchase, Preauth, and Verify endpoints allow you to pass an invoice object in your request. This object is used by the Helcim system to create the subsequent invoice that is associated with the payment.

Payments endpoints

Create transaction objects by processing credit card payments using the following endpoints.

• 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

Retrieve existing transaction objects using the following endpoints.

• Get transactions
• Get transaction