Process a credit card payment

The Process Purchase Transaction endpoint can be used to create a new credit card payment through the Helcim system. This endpoint will accept a combination of header and body parameters and return a response indicating the outcome of the transaction.

Purchase requests

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

The Purchase 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 Purchase Transaction API Reference

// Example Purchase 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/purchase', options)
  .then(response => response.json())
  .then(response => console.log(response))
  .catch(err => console.error(err));

Processing with a valid cardToken

Processing a credit card payment through the Process Purchase 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 purchase 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 Purchase Transaction endpoint will respond to all requests with either:

• A transaction object with a type of "purchase", 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": 25565370,
  "dateCreated": "2024-05-13 16:26:00",
  "cardBatchId": 3559552,
  "status": "APPROVED",
  "user": "Helcim System",
  "type": "purchase",
  "amount": 100.99,
  "currency": "CAD",
  "avsResponse": "X",
  "cvvResponse": "",
  "cardType": "MC",
  "approvalCode": "T2E8ST",
  "cardToken": "2f7c46a9aa15c52da72380",
  "cardNumber": "5454545454",
  "cardHolderName": "John Doe",
  "customerCode": "CST1035",
  "invoiceNumber": "INV1267",
  "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": "purchase",
  "amount": 100.99,
  "currency": "CAD",
  "avsResponse": "X",
  "cvvResponse": "",
  "cardType": "MC",
  "errors": "Transaction Declined: DECLINE CVV2 - Do not honor due to CVV2 mismatch\\failure"
}