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