How to set up Gonnado's POS System API by Webhook?

How can I connect my POS System with Gonnado's POS System API by Webhook, as an Alternative when no Plugin is available.

Summary

This Webhook can be used to programatically redeem coupons which were issued by the Gonnado App. The main use case is automatically redeeming coupons at the point of sale by integrating with a POS system. 

API Endpoints

https://gonnado.com/en/business/redemption_webhook Production
https://staging.gonnado.com/en/business/redemption_webhook Testing

Authentication


The endpoint only accepts HTTP requests with the POST method that provide an authentication token. This token can either be added as a request header or in the body of the request.

Gonnado API Key

Each request needs to be authenticated with an API key. The key is a 64-digit alphanumeric hash.

To obtain an API key, visit the gonnado business interface. Navigate to your account settings and click on the link “Gonnado API”. Copy the existing API token or generate a new key.

Example Key: b2eead2681536de4b250ff97cd3c9059ed3f603f6f691de73c8fc154af5785a34

Authenticating via HTTP Header

The request can be authenticated by adding the Authentication header containing a valid gonnado API key.

Example

curl -i -X "POST" --header "Authentication: <api_key>" \
https://staging.gonnado.com/en/business/redemption_webhook

Authenticating via POST body

If adding headers to the request is not possible, one can authenticate by sending the key in the body of the HTTP request.


Example

curl -i -X "POST" \
--header "Content-Type: application/json" \
--data= '{ "apiKey": "<api_key>" }'
https://staging.gonnado.com/en/business/redemption_webhook

If the API key is valid, the endpoint should return 204 NO CONTENT, which can be interpreted as a sucessful response.

 

Request Data

The endpoint expects a valid, flat, UTF-8 encoded JSON object. The request body needs to be encoded with Content-Type: application/json.

JSON Schema

{
"$schema": "http://json-schema.org/draft-07/schema#",
"title": "Gonnado Ads API Coupon redemption Webhook",
"type": "object",
"properties": {
"apiKey": {
"type": "string",
"description": "Gonnado Ads API key. If not provided in the request header, this field is required.",
"examples": [
"b2eead2681536de4b250ff97cd3c9059ed3f603f6f691de73c8fc154af5785e34"
]
},
"redemption_timestamp": {
"type": "string",
"description": "Time of redemption formatted as ISO 8601 timestamp.",
"examples": [
"2019-02-04T20:17:39.419Z"
]
},
"redemption_code": {
"type": "string",
"description": "Coupon Code as provided by client to gonnado. If external_customer_id is not provided, this field is required."
},
"external_customer_id": {
"type": "string",
"description": "Hashed consumer ID from a list that was given to gonnado.",
"examples": [
"ffd1128de08225d4e35c6681e102145901f3905e9fbe1372d606287d84adc614"
]
},
"redemption_value": {
"type":"number",
"description": "The basket value of the transaction. Can be either an integer or a floating point number.",
"examples": [
15.95,
15
]
}
},
"required": [
"redemption_timestamp",
"redemption_value"
]
}


Example

curl -i -X "POST" \
https://staging.gonnado.com/en/business/redemption_webhook \
-H "Authentication: <api_key>" \
-H "Content-Type: application/json" \
-d '{
"redemption_timestamp":"2019-02-04T20:17:39.419Z",
"external_customer_id":"ffd1128de08225d4e35c6681e102145901f3905e9fbe1372d606287d84adc614",
"redemption_value": 15.95
}'
 

Errors / Troubleshooting

HTTP Response Code Error description
500 We are experiencing problems with our service
422 Decoding JSON failed or the given timestamp does not conform to ISO 8601
401 Not Authorized. Ensure that the API key is valid and properly included in the request.
400 Valid authentication but invalid request body. Ensure that all required fields are included
204 Valid authentication but empty request body.
404 Coupon does not exist.
200 Coupon was redeemed successfully.