Voucher Request API

Overview

The Voucher Request API issues promotional voucher codes when customers purchase specific products. When a customer buys a product (e.g. Paysafecard), your POS system reports the purchase category to receive a promotional voucher code from a participating merchant (e.g. bet-at-home free bet).

Important: The voucher code returned is NOT for the product purchased. It's a promotional bonus from a different merchant. For example:

• Customer purchases a Paysafecard (PAY category)
• API returns a bet-at-home free bet voucher code (promotional bonus)
• Customer receives both their Paysafecard AND the promotional voucher

Endpoint

Invoke the endpoint once per voucher that needs to be dispensed. The platform automatically selects the correct promotional campaign based on the product category that was purchased.

Request Headers

Request Body

{
  "distributor_id": "DIST-001",
  "terminal_id": "AT-998877",
  "trigger_category_id": "PAY",
  "trigger_product_id": "PaySafeCard"  // optional
}

Responses

Note: All responses return proper HTTP status codes. Success is indicated by 2xx codes, errors by 4xx/5xx codes. Response bodies are always JSON.

Success — 200 OK

{
  "campaign_id": "CAMP-BETATHOME-001",
  "voucher_code": "BET-XYZ-987654",
  "expiry_date": "2026-03-31T23:59:59Z",
  "issued_at": "2025-01-20T14:30:00Z"
}

Important: The voucher_code is from the promotional merchant (e.g., bet-at-home), NOT a code for the product the customer purchased.

Error Responses

Error responses return an appropriate HTTP status code with a JSON body containing a human-readable message:

{
  "message": "voucher unavailable"
}

Error Codes

Trigger Categories

When a customer purchases a product, your POS system reports the category to receive promotional vouchers. Each category represents a group of related products:

Example Promotional Campaign: A betting merchant (bet-at-home) creates a campaign targeting PAY purchases. When customers buy Paysafecard (PAY category), they receive a bet-at-home free bet voucher as a promotional bonus.

Integration Guide

Sample cURL

curl \
  -X POST "https://sandbox.ckedw.com/api/v1/voucher/request" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{
    "distributor_id": "DIST-001",
    "terminal_id": "AT-998877",
    "trigger_category_id": "PAY",
    "trigger_product_id": "PaysafeCard"
  }'

Sample Response:

{
  "campaign_id": "CAMP-BETATHOME-001",
  "voucher_code": "BET-ABC-123456",
  "expiry_date": "2026-03-31T23:59:59Z",
  "issued_at": "2025-10-29T10:15:30Z"
}

Sandbox Testing Guide

This sandbox environment contains pre-populated test data for integration testing. Use the resources below to validate your integration before moving to production.

Available Test Distributors

Active Test Campaigns

Over 100,000 test vouchers are available across the following campaigns:

Authentication & Credentials

Authorization Bearer tokens are unique per distributor and will be provided by our support team.

To request sandbox credentials:

• Contact our integration support team
• Provide your company name and intended use case
• You will receive a distributor ID and corresponding Bearer token

Testing Recommendations

Terminal IDs

You can use any terminal ID in your testing (e.g., TEST-TERMINAL-001, TEST-POS-123, etc.). Terminal IDs are logged for audit purposes but do not affect voucher allocation.

Sample Test Request

Example 1: With optional product ID (recommended for analytics)

curl \
  -X POST "https://sandbox.ckedw.com/api/v1/voucher/request" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  -d '{
    "distributor_id": "DIST-TEST-001",
    "terminal_id": "TEST-TERMINAL-001",
    "trigger_category_id": "PAY",
    "trigger_product_id": "PaySafeCard"
  }'

Example 2: Without optional product ID (still works, but less detailed analytics)

curl \
  -X POST "https://sandbox.ckedw.com/api/v1/voucher/request" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  -d '{
    "distributor_id": "DIST-TEST-001",
    "terminal_id": "TEST-TERMINAL-001",
    "trigger_category_id": "PAY"
  }'