VoucherVerse
Developers

Codes API

Validate, allocate and redeem a campaign's voucher codes from any system: a chatbot, a website backend, a mobile app's server or a till. Every endpoint is a JSON POST, and the campaign's API key decides which campaign it acts on.

EndpointWhat it does
POST /public/v1/codes/validateChecks that a code exists in the campaign and can still be redeemed.
POST /public/v1/codes/allocateGives a code to someone.
POST /public/v1/codes/redeemUses up a pending or allocated code.
https://your-voucherverse-domain

Authentication

Send the campaign's API key as a bearer token on every request:

Authorization: Bearer vvb_...
  1. In the dashboard, open Campaigns, your campaign, then API access and Generate key. There is one key per campaign.
  2. Copy it straight away. It is shown once; VoucherVerse keeps only a hash of it.
  3. Rotate key issues a new one. The old key stops working immediately, so update your systems straight after.

Keep the key on your server (webhook, backend, till software). Never put it in a website's JavaScript or a mobile app: anyone who has it can allocate and redeem this campaign's codes.

Other ways into VoucherVerse use different credentials:

APIForCredentials
/public/infobip/*Infobip Answers botsInstall VoucherVerse from Infobip Exchange. Infobip signs each call; the campaign API key goes in the block's key field. See below.
/public/campaigns/{campaignId}/vouchers/{code}/redeemMerchant tills and POSA merchant user's key in X-API-Key. Works for any campaign of that merchant's company.
/api/*The VoucherVerse dashboardA session token from signing in (JWT, 24 hours). Not meant for integrations.

Code states

PENDING ──allocate──▶ ALLOCATED ──redeem──▶ REDEEMED
   │                                            ▲
   └──────────────────redeem────────────────────┘
PENDING or ALLOCATED ──expire (dashboard)──▶ EXPIRED

PENDING codes were generated or imported and belong to nobody yet. ALLOCATED codes belong to a customer or to your recipient ID. Both can be redeemed, and redeeming a pending code records the participant. Pre-printed codes go straight from pending to redeemed.

Samples in

Validate a code

POST/public/v1/codes/validate

Checks that a code exists in the campaign and can still be redeemed. Nothing changes.

FieldDescription
coderequiredThe code the person typed. Surrounding spaces and letter case are ignored. Max 64 characters.
participantrequiredWho is acting: a stable ID such as a phone number in international format, your user ID, or a till ID. Used for the rate limit and recorded on the code. Max 128 characters.
curl -X POST https://your-voucherverse-domain/public/v1/codes/validate \
  -H "Authorization: Bearer $VOUCHERVERSE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"code":"VVX7K2M9QP","participant":"27821234567"}'
Response 200
{
  "ok": true,
  "status": "VALID",
  "code": "VVX7K2M9QP",
  "message": "This code is valid.",
  "prize": "",
  "prizeDescription": "",
  "prizeCode": ""
}
  • Validating does not reserve the code. Redeem checks everything again, so you can call redeem on its own.

Allocate a code

POST/public/v1/codes/allocate

Gives a code to someone. Leave out code to get the next pending code (for example when a chatbot user asks for a voucher), or pass one to allocate that exact code.

FieldDescription
codeoptionalAllocate this pending code (letter case is ignored). Omit to take the next pending code.
customerEmailone ofThe customer's email, stored and matched in lower case. Finds or creates the customer in your company. An address that isn't a valid email is refused with 400.
customerPhoneone ofThe customer's phone number: digits with the country code first, e.g. 27821234567 (a leading + is optional). A local number starting with 0 is refused with 400.
externalIdone ofYour own ID for the recipient, stored on the code. One line, at most 128 characters.
curl -X POST https://your-voucherverse-domain/public/v1/codes/allocate \
  -H "Authorization: Bearer $VOUCHERVERSE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"customerEmail":"jane@example.com","customerPhone":"27821234567","externalId":"crm-10492"}'
Response 200
{
  "ok": true,
  "status": "ALLOCATED",
  "code": "VVX7K2M9QP",
  "value": 10,
  "expiresAt": "2026-12-31T00:00:00Z",
  "customerId": "6ab63866289f9e796e87f1de",
  "externalId": "crm-10492",
  "message": "Here is your code."
}
  • Give at least one of customerEmail, customerPhone or externalId.
  • Taking the next code is atomic: two requests at the same moment never get the same code.
  • Allocation works before the campaign starts, so codes can be sent ahead of launch.

Redeem a code

POST/public/v1/codes/redeem

Uses up a pending or allocated code. Each code can be redeemed once.

FieldDescription
coderequiredThe code to redeem. Surrounding spaces and letter case are ignored.
participantrequiredWho is acting: a stable ID such as a phone number in international format, your user ID, or a till ID. Used for the rate limit and recorded on the code. Max 128 characters.
curl -X POST https://your-voucherverse-domain/public/v1/codes/redeem \
  -H "Authorization: Bearer $VOUCHERVERSE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"code":"VVX7K2M9QP","participant":"27821234567"}'
Response 200
{
  "ok": true,
  "status": "REDEEMED",
  "code": "VVX7K2M9QP",
  "message": "Thanks, your code has been redeemed. You won a free meal! Your prize code is MEAL-4KD9.",
  "prize": "a free meal",
  "prizeDescription": "Show this at the counter.",
  "prizeCode": "MEAL-4KD9"
}
  • If two requests redeem the same code at the same moment, exactly one gets REDEEMED; the other gets ALREADY_REDEEMED.
  • Prize draws: if the campaign runs one, a redemption may win a prize. prize, prizeDescription and prizeCode say what (prizeCode is a code from another campaign, when the prize comes with one), and message adds "You won …!". The status is still REDEEMED. Every response carries these fields; they are empty strings when nothing was won.

Statuses and errors

Business outcomes, including refusals, come back as 200 with ok and a status to branch on. message is a suggested reply for the person, which you can show as-is or replace.

statusokFromMeaning
VALIDtruevalidateThe code exists and can be redeemed.
ALLOCATEDtrueallocateThe code now belongs to the recipient; it is in code.
REDEEMEDtrueredeemThe code was used up just now.
NOT_FOUNDfalseallNo such code in this campaign.
ALREADY_ALLOCATEDfalseallocateThat code already belongs to someone.
ALREADY_REDEEMEDfalseallThe code was redeemed before.
EXPIREDfalseallThe code was expired.
NO_CODES_LEFTfalseallocateNo pending codes left. Generate or import more in the dashboard.
CAMPAIGN_CLOSEDfalseallThe campaign is inactive or has ended (validate and redeem also refuse before it starts), or the company's VoucherVerse plan is unpaid or has ended.
RATE_LIMITEDfalsevalidate, redeem10 rejected codes from this participant in the last hour. Ask them to try later.

Errors use other HTTP codes, with the same JSON shape:

HTTPstatusWhen
400BAD_REQUESTInvalid JSON; missing code or participant (validate, redeem); no recipient (allocate).
401INVALID_KEYThe API key is missing, wrong or rotated. The response carries WWW-Authenticate: Bearer.
500ERRORSomething went wrong on our side. Retry with backoff; a redeem that failed did not use up the code.

Limits and rules

  • One redemption per code. Redeeming is atomic.
  • Rate limit. After 10 rejected codes (not found, already redeemed, expired) from one participant in an hour, validate and redeem answer RATE_LIMITED. This stops code guessing. Successful calls don't count.
  • Matching. " vvx7k2m9qp " finds VVX7K2M9QP. The response's code is the code as stored.
  • Campaign dates. Validate and redeem work only while the campaign is active and within its dates. Allocate also works before it starts.
  • Timeouts. Allow 10 seconds. Calls normally take well under a second.

Example: a chatbot

A promo where people type a code from the packaging into WhatsApp. Your bot's webhook calls redeem and answers with the result:

// Express-style webhook in your chatbot backend
app.post("/bot/code", async (req, res) => {
  const { text, from } = req.body; // what the user typed, their phone number
  const r = await fetch("https://your-voucherverse-domain/public/v1/codes/redeem", {
    method: "POST",
    headers: { Authorization: `Bearer ${process.env.VOUCHERVERSE_API_KEY}`, "Content-Type": "application/json" },
    body: JSON.stringify({ code: text, participant: from }),
  }).then((x) => x.json());

  if (r.ok) return res.json({ reply: "Thanks, your code is redeemed!" });
  return res.json({ reply: r.message }); // not found, already used, try later...
});

To hand out codes instead (“send me a voucher”), call allocate with the user's phone number and reply with the returned code.

Try it

Sends a real request from your browser. Validate is read-only; allocate and redeem change real codes, so use a test campaign.

POST /public/v1/codes/validate

Infobip without code

Bots built in Infobip Answers don't need any of the above. Install VoucherVerse from Infobip Exchange and add the validateCode and redeemCode blocks. Put the campaign API key in each block's key field, and map code and participant to bot attributes. The blocks return the same fields and statuses as this API. Infobip signs every call, so they use their own endpoints (/public/infobip/*) rather than this API.