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
Base URL
https://ckedw.com
Authentication
Each distributor receives a dedicated Bearer token. Include it with every request to validate the distributor's identity.
Endpoint
POST
/api/v1/voucher/request
Returns one promotional voucher per request.
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
| Header | Value | Notes |
|---|---|---|
| Content-Type | application/json | Required |
| Authorization | Bearer <token> | Required. Token is unique per distributor. |
Request Body
{
"distributor_id": "DIST-001",
"terminal_id": "AT-998877",
"trigger_category_id": "PAY",
"trigger_product_id": "PaySafeCard" // optional
}
| Field | Type | Description |
|---|---|---|
| distributor_id | string | Required. Identifier issued by the platform. Must be whitelisted for the target campaign. |
| terminal_id | string | Required. Unique POS or device identifier for audit trails. |
| trigger_category_id | string | Required. The category of product the customer purchased (e.g., "PAY", "GAM", "TRV", "MOB"). This determines which promotional campaign matches. |
| trigger_product_id | string | Optional. Specific product purchased for analytics (e.g., "PaySafeCard", "SteamCard"). Used for tracking which products drive most promotional voucher claims. |
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.
| Field | Type | Description |
|---|---|---|
| campaign_id | string | Unique identifier of the promotional campaign that issued this voucher. |
| voucher_code | string | The promotional voucher code to give to the customer. This code is from the campaign merchant. |
| expiry_date | string (ISO 8601) | When the promotional voucher expires (inherited from campaign end_at date). May be empty for non-expiring campaigns. |
| issued_at | string (ISO 8601) | Server timestamp when the voucher was issued. |
Error Responses
Error responses return an appropriate HTTP status code with a JSON body containing a human-readable message:
{
"message": "voucher unavailable"
}
Error Codes
| Status | Error | Description |
|---|---|---|
| 400 | invalid request | Malformed JSON payload or missing mandatory fields (distributor_id, terminal_id, trigger_category_id). |
| 409 | voucher unavailable | No eligible promotional campaign for the triggered category, or no remaining codes in the campaign pool. |
| 401 | unauthorized | Missing or invalid Authorization Bearer token. |
| 405 | method not allowed | HTTP method other than POST used for the voucher endpoint. |
| 500 | internal server error | Unexpected platform failure. Retry with exponential backoff. |
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:
| Category ID | Description | Example Products |
|---|---|---|
| PAY | Payment products | Paysafecard, Neosurf, Cashlib, A-Bon, etc. |
| GAM | Gaming products | Steam, Xbox, Playstation, Roblox, etc. |
| TRV | Travel & experiences | Jochen Schweizer, Wellcard, Airbnb, airlines, etc. |
| MOB | Mobile top-ups | Vodafone, Orange, O2, MTN, etc. |
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
Workflow
- Customer purchases a product at POS (e.g., Paysafecard)
- POS system calls API with trigger_category_id="PAY"
- API returns promotional voucher from matching campaign
- POS prints/displays both purchased product AND promotional voucher
- Customer receives their purchase plus a bonus promotional voucher
Best Practices
- Always include trigger_product_id for analytics when possible
- Check expiry_date and communicate it clearly to customers
- Handle 409 errors gracefully - campaign may be depleted or ended
Retry Policy
Use exponential backoff for HTTP 5xx responses.
Monitoring
Monitor your API requests for error rates and track voucher availability. Contact the platform team if you experience persistent errors or unexpected voucher unavailability.
Token Management
Partner tokens are maintained by Campaign Distribution Platform. Coordinate token rotation with the platform team; old tokens are revoked immediately after replacement.
Distribution Mapping
Each token is tied to a single distributor_id. Sending a token with a different distributor value results in a 401 response.
Sample cURL
curl \
-X POST "https://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"
}