Skip to main content

Activate Voucher

POST 
/client/users/:correlation_id/voucher/:voucher_id/activate

POST /voucher/{voucherId}/activate — PAC Voucher Activation

Activates a Product Authorization Code (PAC) voucher via an external provider (e.g., Kesseltronics car-wash terminals). Only vouchers with rewardType = PRODUCT_AUTHORIZATION_CODE can be activated.

Path Parameters​

ParamTypeDescription
correlationIdstringSession correlation ID
voucherIdstringVoucher issuance code, format: {definitionId}::{issuanceUuid}

Request​

No body. All input is conveyed via path + session context (OAuth token → account).

Preconditions​

  1. Voucher exists under the current session's account → else 404 VOUCHER_NOT_FOUND
  2. Voucher is in AVAILABLE state → else 409 VOUCHER_NOT_AVAILABLE (e.g., already REDEEMED, EXPIRED, INVALIDATED)
  3. Voucher definition has rewardType = PRODUCT_AUTHORIZATION_CODE → else 400 INVALID_VOUCHER_TYPE
  4. Provider is configured on the voucher definition → else 422 PROVIDER_NOT_CONFIGURED

Activation Flow​

  1. Load voucher instance + hydrate definition via BatchGetItem
  2. Idempotency check: if activation.activatedAt present and codeExpiry in future → return existing code, skip provider call (flag idempotent: true)
  3. Call provider (e.g., Kesseltronics) → receive authorizationCode
  4. Atomic write: transition instance status → ACTIVATED, persist activation.{activatedAt, provider, codeExpiry, authorizationCode} — partial writes are rejected
  5. Emit VoucherEvents: ACTIVATED entry
  6. Return response

Idempotency​

Duplicate calls within the active activation window return the same authorization code without hitting the provider. Detection is based on:

  • activation.activatedAt present, AND
  • activation.codeExpiry in the future

After expiry, the voucher returns to a re-activatable state and a new provider call is made. Response includes idempotent: true on the duplicate case.

Response — 200​

FieldTypeDescription
authorizationCodestringPAC returned by provider
voucherIdstringEcho of path param
statusstringAlways ACTIVATED
providerstringe.g., KESSELTRONICS
productNamestringDisplay name (e.g., Car Wash)
activatedAtstringISO-8601
codeExpirystringISO-8601 — when the code is no longer usable at the terminal
idempotentbooleanPresent = true only when call was a duplicate (no new provider hit)

Error Responses​

StatuserrorCodeWhen
400INVALID_VOUCHER_TYPENot a PAC voucher
401—Missing/expired OAuth token
404VOUCHER_NOT_FOUNDVoucher doesn't exist under this account
409VOUCHER_NOT_AVAILABLEAlready redeemed, expired, or invalidated
422PROVIDER_NOT_CONFIGUREDVoucher definition missing activation provider config
500—Unexpected server error
502EXTERNAL_SERVICE_RESPONSE_ERRORProvider returned malformed/unparseable response
504EXTERNAL_SERVICE_TIMEOUTProvider did not respond within timeout

Console (CSR) Note​

CSRs can VIEW activation status but cannot activate on behalf of the member — activation requires the member to be present at the terminal (security policy).

  • GET .../issuances?type=VOUCHER — find PAC vouchers (rewardType=PRODUCT_AUTHORIZATION_CODE + no activation.activatedAt)

Request​

Responses​

200 - Activation Successful

Last updated on