Integration Flow

This guide walks through the complete POS integration flow: fetching the configuration, issuing containers, previewing a transaction, and processing returns.

Full Flow Overview

Step 1: Fetch Configuration

Before creating transactions, your POS should fetch the current Hybrid Revo Token configuration to know which products trigger container issuance.

curl -X GET https://api.dev.votesess.com/v1/integrations/hybrid-revo-token-configurations \
  -H "X-API-Key: YOUR_API_KEY"

Response:

{
  "id": "config_001",
  "createdAt": "2026-01-10T08:00:00Z",
  "currentVersion": {
    "id": "ver_001",
    "createdAt": "2026-01-10T08:00:00Z",
    "isEnabled": true,
    "categories": [
      {
        "id": "cat_001",
        "createdAt": "2026-01-10T08:00:00Z",
        "expirationHours": 48,
        "depositGross": 500,
        "revoTokenCategory": {
          "id": "rtc_001",
          "name": "0.5L Cup",
          "description": "Standard half-liter reusable cup",
          "currencyCode": "HUF"
        },
        "products": [
          {
            "id": "prod_mapping_001",
            "createdAt": "2026-01-10T08:00:00Z",
            "productId": "beer_500ml"
          }
        ]
      }
    ]
  }
}

Use this data to:

• Build a mapping of productId to container category
• Know the deposit amounts to charge the guest
• Cache the configuration and refresh periodically

tip

Check the isEnabled field before proceeding. If the configuration is disabled, do not issue Hybrid Revo Tokens.

Step 2: Create Transaction (Issue Containers)

When a guest purchases products that include reusable containers, create a transaction by sending the product IDs and quantities.

curl -X POST https://api.dev.votesess.com/v1/integrations/hybrid-revo-token-transactions \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '[
    { "productId": "beer_500ml", "quantity": 2 },
    { "productId": "wine_300ml", "quantity": 1 }
  ]'

Response:

{
  "id": "txn_abc123",
  "createdAt": "2026-03-15T14:30:00Z",
  "code": "HRT1234567890ABCDEF1234567890ABCDEFGHIJ",
  "categorySummaries": [
    {
      "revoTokenCategory": {
        "id": "rtc_001",
        "name": "0.5L Cup",
        "currencyCode": "HUF"
      },
      "activeItemCount": 2,
      "expiresAt": "2026-03-17T14:30:00Z"
    },
    {
      "revoTokenCategory": {
        "id": "rtc_002",
        "name": "0.3L Cup",
        "currencyCode": "HUF"
      },
      "activeItemCount": 1,
      "expiresAt": "2026-03-17T14:30:00Z"
    }
  ]
}

What to do with the response:

• Display or print the code for the guest (on receipt, as QR code, etc.)
• The categorySummaries confirm what was issued and when each category expires

Step 3: Preview Transaction

Before processing a return, you can preview the current state of a transaction to see how many active containers remain per category.

curl -X GET https://api.dev.votesess.com/v1/integrations/hybrid-revo-token-transactions/HRT1234567890ABCDEF1234567890ABCDEFGHIJ/preview \
  -H "X-API-Key: YOUR_API_KEY"

Response:

[
  {
    "category": {
      "id": "cat_001",
      "expirationHours": 48,
      "depositGross": 500,
      "revoTokenCategory": {
        "id": "rtc_001",
        "name": "0.5L Cup",
        "currencyCode": "HUF"
      }
    },
    "activeItemCount": 2
  },
  {
    "category": {
      "id": "cat_002",
      "expirationHours": 48,
      "depositGross": 300,
      "revoTokenCategory": {
        "id": "rtc_002",
        "name": "0.3L Cup",
        "currencyCode": "HUF"
      }
    },
    "activeItemCount": 1
  }
]

Use the activeItemCount per category to show the operator how many containers can still be returned and the depositGross to calculate the refund amount.

Step 4: Validate Transaction (Return Containers)

When a guest returns containers, send the transaction code with the category IDs and quantities to return.

curl -X POST https://api.dev.votesess.com/v1/integrations/hybrid-revo-token-transactions/HRT1234567890ABCDEF1234567890ABCDEFGHIJ/validate \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '[
    { "hybridRevoTokenCategoryId": "cat_001", "quantity": 2 }
  ]'

Response:

[
  {
    "category": {
      "id": "cat_001",
      "expirationHours": 48,
      "depositGross": 500,
      "revoTokenCategory": {
        "id": "rtc_001",
        "name": "0.5L Cup",
        "currencyCode": "HUF"
      }
    },
    "validatedCount": 2,
    "remainingItemCount": 0
  }
]

What to do with the response:

• validatedCount -- number of containers successfully returned in this request
• remainingItemCount -- number of active containers still left on this transaction
• Calculate the refund: validatedCount * depositGross (in this case: 2 x 500 = 1000)

note

The quantity in the validate request must be at least 1 and cannot exceed the number of active items for that category. If it does, the API returns a 400 error with code HYBRID_REVO_TOKEN_TRANSACTION_NOT_ENOUGH_ACTIVE_ITEMS.