Preauthorize a credit card payment

The Process Preauth Transaction endpoint can be used to preauthorize a credit card payment through the Helcim system. A preauthorized payment can be partially or fully captured within 7 days of the original payment, through the Process Capture Transaction endpoint. This endpoint will accept a combination of header and body parameters and return a response indicating the outcome of the transaction.

🚧

Capture Timeframes

Preauthorized payments must be captured within 7 days of processing, or they will automatically expire.

Preauth requests

The Process Preauth Transaction endpoint will allow you to process a one time preauthorized credit card payment.

The Preauth API Reference outlines the required and optional body parameters needed for your request. The minimum required information in the body of your request includes a valid cardData object that contains a cardToken, the ipAddress where the payment is processed, the currency of the payment, and the amount of the payment.

Review Process Preauth Transaction API Reference

// Example Preauth request
const options = {
  method: 'POST',
  headers: {
    accept: 'application/json',
    'idempotency-key': 'Idempotency20240514test01',
    'content-type': 'application/json',
    'api-token': 'YOUR_API_TOKEN'
  },
  body: JSON.stringify({
    cardData: {cardToken: '2f7c46a9aa15c52da72380'},
    ipAddress: '192.168.1.1',
    currency: 'CAD',
    amount: 100.99
  })
};

fetch('https://api.helcim.com/v2/payment/preauth', options)
  .then(response => response.json())
  .then(response => console.log(response))
  .catch(err => console.error(err));

In order to capture a preauthorized payment, a request should be sent to the Process Capture Transaction endpoint. Alternatively the payment can be manually captured in the Payments section of your Helcim account.

Learn more about how to capture a preauthorized payment.

Processing with a valid cardToken

Processing a credit card payment through the Process Preauth Transaction endpoint requires a valid cardToken in order to process with, to reduce your integrations PCI compliance scope.

We recommend implementing HelcimPay.js initialized with the preauth paymentType in order to process your customers initial payment and create your cardToken value for future payments through the Payment API.

Potential payment responses

The Process Preauth Transaction endpoint will respond to all requests with either:

• A transaction object with a type of "preauth", indicating the outcome of the payment.
• An error response indicating the reason for the error.

Potential payment outcomes

A successful payment request will create a transaction object in the Helcim system with a status that indicates the outcome of the payment.

• A successful payment will contain a status with the value of 'APPROVED'.

// Example APPROVED transaction object
{
  "transactionId": 25597748,
  "dateCreated": "2024-05-15 08:58:01",
  "cardBatchId": 3567154,
  "status": "APPROVED",
  "user": "Helcim System",
  "type": "preauth",
  "amount": 100.99,
  "currency": "CAD",
  "avsResponse": "X",
  "cvvResponse": "",
  "cardType": "MC",
  "approvalCode": "T7E5ST",
  "cardToken": "2f7c46a9aa15c52da72380",
  "cardNumber": "5454545454",
  "cardHolderName": "John Doe",
  "customerCode": "CST1035",
  "invoiceNumber": "INV1270",
  "warning": ""
}

• An unsuccessful payment will contain a status with the value of 'DECLINED'. It will also contain an errors value that contains more information on why the payment was declined.

// Example DECLINED transaction object
{
  "transactionId": 25565636,
  "dateCreated": "2024-05-13 16:35:26",
  "cardBatchId": 0,
  "status": "DECLINED",
  "user": "Helcim System",
  "type": "preauth",
  "amount": 100.99,
  "currency": "CAD",
  "avsResponse": "X",
  "cvvResponse": "",
  "cardType": "MC",
  "errors": "Transaction Declined: DECLINE CVV2 - Do not honor due to CVV2 mismatch\\failure"
}