TalkBox vouchers can be issued as either QR codes or string codes depending on the redemption mechanism being used. Usually, vouchers are sent as QR codes if they’re going to be scanned with POS hardware on-site, while string codes are better suited to online checkouts, like baskets.
Adding TalkBox voucher redemption to an existing online checkout system is simple.
Accept the voucher code
You’ll need to add a new form form field for the checkout workflow to enter the string code. Nothing special is required here, you could add some simple client side validation such as confirming the string is the correct length but that’s optional.
If your checkout system supports vouchers from multiple systems you’ll need a way to identify the code as a TalkBox code. TalkBox accounts can be configured to use a fixed voucher prefix, if you would like this set up for your account please contact our support team.
TOP TIP: TalkBox accounts can be configured to use a fixed prefix like a number or word unique to your business. Please contact support team if this is for you.
Fetch the voucher from TalkBox
This is an authenticated API call so should not be done client side. It’s a simple GET request that looks like this with no additional parameters. (Read more about our API including authentication here.)
https://talkbox.impactapp.com.au/service/v1/vouchers/{string code}
For example, the following request
GET https://talkbox.impactapp.com.au/service/v1/vouchers/KQCSLNWS
will return a JSON document like this.
{
"id": 16932356,
"description": "This voucher is valid for one free medium coffee",
"redeemed_at": null,
"created_at": "2022-03-31T17:46:20+11:00",
"name": "Free coffee",
"valid_to": null,
"valid_from": null,
"string_id": "KQCSLNWS",
"user_data": {
"pos_promocode_id": "10003"
},
"expires_at": null,
"valid_weekdays": [
"Monday",
"Tuesday",
"Wednesday"
],
"valid_time": [
"18:00",
"20:00"
],
"status": "violates_weekday_time_restriction",
"url": "https://talkbox.impactapp.com.au/recipients/nIicFmd_d3krgZr4nn5Haw==/_/offers/myOgJ-3COnKMkAirN00uXA==/voucher?id=KXSzlTncjpWckporsgS8WQ%3D%3D",
"contact_id": 78546800,
"communication_id": 16904743,
"promotion_id": 12545779,
"external_identifier": "123"
}
The possible values for status are:
| redeemable | voucher is valid and can be redeemed now |
| redeemed | voucher has already been used and cannot be redeemed again |
| before_valid_period | voucher is not yet valid (valid_from date is in the future) |
| after_valid_period | voucher has expired (valid_to date or expires_at is in the past) |
| violates_weekday_time_restriction | voucher is not valid due to the weekday and/or time restrictions. |
The user_data field is available to store arbitrary key-value pairs that are meaningful to the system redeeming the voucher. The data stored in this field is not used by TalkBox but can be used to control redemption logic. Examples of common usage are:
| { percentage_discount = 20 } | Apply a blanket percentage discount to the transaction. |
| { dollar_discount = 5, minimum_spend = 50 } | Apply a conditional cash discount. Note that multiple parameters can be used together. |
| { discount_code = 12B } | A reference to a discount code in the redemption system. |
Modify the transaction
Here the voucher is applying a 15% discount to the transaction. We recommend displaying this to the user explicitly, which includes the total before the discount has been applied. (The discount and then the new total.)
Redeem the voucher
On submission and confirmation of a successful transaction, send the request to redeem the TalkBox voucher. This changes the state of the voucher to redeemed and prevents the voucher from being used again.
A TalkBox voucher can be redeemed by issuing a PUT request to the URL from the QR code with the parameter voucher[redeemed]=1.
If the voucher is successfully redeemed the server will respond with HTTP 200 and return the JSON data for the voucher with a redeemed_at value.
To fully describe this, a request using cURL to redeem a voucher would be of the form
curl --request PUT --url '<voucher_url>?voucher[redeemed]=1'
The full cURL command for the example voucher above would then be.
curl --request PUT --url 'https://talkbox.impactapp.com.au/recipients/cRp2zQ6dwTtYPkbFO2qmDA==/_/offers/CPa2vRbheZivyMxhF-bHzg==/voucher?id=5rF7VSgbb-AIhODnJtyCDA%3D%3D&voucher[redeemed]=1'
Feel free to check out any other support articles listed below.
If you have questions please reach out to the team at support@impactdata.com.au