Initiating a debit refund transaction

Once your Smart Terminal is paired to your third-party point of sale system or software, by saving the device code in your system or making it otherwise available for transactions, you can initiate a Debit Refund Transaction that is sent to your Smart Terminal via the Smart Terminal API.

To facilitate future Refund Transactions within your integration, you should be storing the cardType returned by the Smart Terminal API on successful transactions so that you know whether to process a Credit Card or Debit Card Refund if the situation arises.

Before sending a request to the Smart Terminal API to process an in-person Debit Card Refund, please ensure that you have completed the configuration steps outlined in our Smart Terminal API overview.

🚧

This documentation is for processing in-person Debit Card Refunds through the Helcim Smart Terminal API.

For Credit Card Refunds, these do not require an in-person transaction and can be processed immediately through our Payment API using the Process Refund Transaction endpoint.

Building your Smart Terminal API debit refund transaction request

In order to initiate a Debit Refund Transaction from your existing software, a POST request should be sent to the Smart Terminal API Refund endpoint from your systems secure back end server.

📘

A Debit Card Refund sent to a Smart Terminal device, must be for a successful transaction in a closed payment batch, and requires the end customer to be present with the original purchasing card to complete.

Required parameters

Headers

• api-token: The API token for the Helcim account your devices are registered with.
• idempotency-key: The unique 25 character alphanumeric key associated with this transaction.

Path parameters

• code: Your 4 digit alphanumeric device code.

Body parameters

• currency: The currency that you would like to process the transaction in. This should match the core currency of your business location (E.g., Canadian merchants = CAD and United States merchants = USD).
• transactionAmount: The amount to be refunded, to two decimal places. Should be less than or equal to the original transactionAmount.
• originalTransactionId: The transactionId of the original transaction that you would like to refund. Returned by the response or transaction webhook event for the original transaction.

If your request is successful, the Smart Terminal will prompt the refund flow for the payment on the device. The customer can then tap or use chip + PIN to complete the refund.

Example request

To build your Debit Refund Transaction request in your preferred language, visit our API reference page here.

const options = {
  method: 'POST',
  headers: {
    accept: 'application/json',
    'idempotency-key': 'test-helcim-20240405-0001',
    '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 Smart Terminal 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 Smart Terminal API encountered an unknown error when trying to process your request.

Debit Refund Transactions processed on a Smart Terminal device through the Smart Terminal API will appear in your Payments list with the Payment Source of Helcim Card Reader and can be filtered to using the filtering tools.