Campaign Distribution Platform

Voucher Request API

Issue promotional voucher codes through a single, low-latency endpoint. This page documents the canonical integration surface for distribution partners.

Overview

The Voucher Request API enables registered distribution partners to pull campaign-specific voucher codes in real time. The platform verifies campaign assignments, enforces capacity rules, and logs each transaction for reconciliation.

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 voucher per request.

Invoke the endpoint once per voucher that needs to be dispensed. The platform automatically selects the correct campaign based on distributor and product category rules.

Request Headers

Header Value Notes
Content-Type application/json Required
Authorization Bearer <partner_token> Required. Token is unique per distributor.
Idempotency-Key <request_id> Optional. Reuse request_id for safe retries.

Request Body

{
  "request_id": "req-1001",
  "distributor_id": "DIST-001",
  "terminal_id": "AT-998877",
  "product_ids": ["PAY", "MOB"]
}
Field Type Description
request_id string Partner-generated correlation ID. Use a UUID or similar unique token.
distributor_id string Identifier issued by the platform. Must be whitelisted for the target campaign.
terminal_id string Unique POS or device identifier for audit trails.
product_ids array<string> Ordered list of product categories to satisfy. The first matching campaign wins.

Responses

Success — 200 OK

{
  "status": "success",
  "campaign_id": "CAMP-001",
  "category_id": "PAY",
  "product_id": "PAY",
  "voucher_code": "PSCF-XYZ-987654",
  "serial_number": "SER-000001",
  "expiry_date": "2025-12-31T00:00:00Z",
  "request_id": "req-1001",
  "issued_at": "2025-10-19T12:00:00Z"
}

Error Codes

Status Error Description
400 invalid request Malformed JSON payload or missing mandatory fields.
409 voucher unavailable No eligible campaign or no remaining codes for the requested product IDs.
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.

Integration Guide

Retry Policy

Use exponential backoff with jitter for HTTP 5xx responses. Replaying the same request_id prevents duplicate vouchers.

Monitoring

Integrate CloudWatch metrics or partner-facing dashboards to react to error spikes or depletion of voucher pools.

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 '{
    "request_id": "req-1001",
    "distributor_id": "DIST-001",
    "terminal_id": "AT-998877",
    "product_ids": ["PAY", "MOB"]
  }'