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
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 atype
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"
}
Updated 3 months ago