Initiating a Debit Refund Transaction

Helcim makes it easy to handle returns directly on your payment hardware. Once you have paired your compatible Helcim devices to your point-of-sale system, you can start a debit refund for eligible transactions through the Payment Hardware API.

To make refunds easier in the future, we recommend storing the card type (credit or debit) returned by the Payment Hardware API during the original sale. This helps you know if you need to process a refund for that payment in person or not.

🚧
Note on credit vs. debit refunds: This guide is for in-person debit card refunds. Credit card refunds do not require the customer to be present and can be processed immediately through our standard Payment API using the Process Refund Transaction endpoint.

Building your debit refund transaction request

To start a debit refund from your software, your secure back-end server must send a POST request to the Payment Hardware API refund endpoint.

A debit card refund sent to payment hardware must be for a successful transaction in a closed payment batch. The customer must be present with their original card to finish the process.

Parameter	Type	Description
`api-token`	string	The unique API token for your Helcim account passed in the header of your request.
`code`	string	The four character alphanumeric code for the device that should process the payment as a path parameter for your request.
`transactionAmount`	number	The amount to be refunded, written to two decimal places. This cannot be more than the original transaction amount.
`originalTransactionId`	integer	The unique id of the original debit card transaction being refunded/

When your request is successful, the payment hardware will prompt the customer to tap or insert their original card to receive the refund.

Example debit refund transaction request

const options = {
  method: 'POST',
  headers: {
    accept: 'application/json',
    'content-type': 'application/json',
    'api-token': 'API_TOKEN'
  },
  body: JSON.stringify({transactionAmount: 100.99, originalTransactionId: 1234567890})
};

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

Refund transaction responses

202 Accepted: Returned when a request to the Payment Hardware API was formed correctly and processed. Does not indicate that the requested action was completed.
403 Unauthorized: Returned when the api-token sent in the header of your request was incorrect, or does not have the valid permissions to complete the request.
404 Device Not Found: Returned when the code sent in the path parameters was not found by the API. This is likely the result of an incorrect code being sent in the request, or the device has not yet been registered with the Helcim system.
409 Device Not Listening: Returned with the code sent in the path parameters exists in our system, but the device is not reachable. This is likely due to the device being powered off, not logged in, or being asleep.
500 Internal Server Error: Returned when the Payment Hardware API encountered an unknown error when trying to process your request.

Viewing your debit refunds

Any debit refunds processed on compatible Helcim devices through the Payment Hardware API will appear in your Helcim account in the transaction list in your Payments tool. You can filter these records by selecting "Helcim Card Reader" as the payment source to see all activity from your payment hardware.