Processing card transactions

The Card Payments API enables Helcim merchants to process credit and debit cards. Transactions types include "purchase", "pre-authorization", "capture", "refund", "void", "verify" and "settle".

📘

Authentication and general API information

The Card Payments API is an extension of the Helcim General API. Please refer to the documentation above for information on authentication, security, TLS ciphers and error handling.

Reducing Your PCI and Security Scope

We strongly advise that you do not store any sensitive cardholder information, including full credit card numbers and expiry dates. Instead, merchants should use the card-tokenization service built into Helcim. There are a number of entry-points for credit card data, including the Virtual Terminal, API, Hosted Payment Pages, Customer Portal, Online Store and Helcim.js. When a transaction is successfully processed using any of these entry entry-points, the credit card is automatically stored, tokenized and added to the customer's card-vault. Using the stored card token, you can process a new transaction anytime without needing the original credit card number.

We therefore strongly recommend using the Helcim Commerce API in conjunction with either Helcim.js or our Hosted Payment Pages for capturing and tokenization full credit card numbers. Further transactions can then be processed through the API using the card token, and since no full credit card numbers are passed, your server remains outside the scope of PCI-DSS compliance.

Sending Invoice Data (Optional)

When processing a card transaction (including "purchase" and "pre-authorization"), an invoice is automatically be create alongside the new card transactions. You can therefore send invoice / order fields along the same transaction request, and the created order will be reflected of the information sent.

Using Card Tokens

Your application should store this card token, as well as the first 4 and last 4 digits of the credit card number. Neither of these fields are considered sensitive cardholder information. When ready to process a new payment, these fields should be sent to the API instead of the credit card number, expiry and CVV fields. The first and last 4 digit is used to ensure that the card you wish to bill is the correct one.

Field Name

Format

Description

cardToken

String (23)

The 23-digit, alpha-numeric card token representing the stored card information.

cardF4L4

Integer (8)

The first 4 and last 4 digits of the card number.

Helcim Card Vault

As part of Helcim's tokenization systems, cards are stored under a customer profile. Each customer has their own "card vault" that can hold as many cards as needed. A default card can be assigned to the customer, letting the system know which card to use when a specific card token is not sent. Cards manually added to the customer card vault can be used through the API, and any cards removed can no longer be used.

(optional alternative)
When processing a new transaction, the customerCode field can be sent instead of the card token fields, and the system will retrieve the default card assigned to this customer.

Field Name

Format

Description

customerCode

String

The customer code as displayed in the Helcim Customer Manager tool.