Heartland Retail supports configuring custom webhooks to handle capturing, refunding, checking gift card balances, etc. via an external service. This is useful for customers who want to integrate a legacy or 3rd party payment method with Heartland Retail. Heartland Retail will call your webhook endpoints at appropriate points throughout the payment processing flow.
NOTE: This is an advanced feature intended for developers. It is up to you to develop, host, manage, and secure your webhook server.
We have an example app on our GitHub account to serve as a reference. It's written in Ruby but you can use any programming environment capable of implementing a web server.
To configure payment webhooks go to Settings -> Payment types and add a new payment type. Once the payment type is created change the "PROCESS PAYMENTS" dropdown to "With custom webhooks". Enter the URL of the HTTPS endpoints you'd like us to call as shown below:
There are three base types of webhooks available to any custom payment type: Capture, Refund, Void. The Gift Card payment type also supports the Check Balance method.
During payment process or gift card balance checking Heartland Retail sends the following request to the configured endpoints.
{
"payment_id": "1",
"amount": "72.95"
}Gift Card payment requests will also contain a gift card number.
{
"number": "EXAMPLE123",
"payment_id": "1",
"amount": "72.95"
}If the request is successful, Heartland Retail expects response with an HTTP status code of 200. Any error response code will fail the operation and show an error to the user. No response body is required (with the exception of "Check Balance" as described below).
When a user needs to check a Gift Card's balance Heartland Retail sends the following request to the "Check Balance" endpoint.
It expects to receive a JSON response body containing the gift card balance:
{
"balance": 12.34
}