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

API: GET /v1/integrations/revo-union-configurations

Before creating transactions, your POS should fetch the RevoUnion configuration to know which products trigger container issuance.

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

Response:

{
  "revoTokenProducts": [
    {
      "id": "rtp_001",
      "action": "BORROW",
      "productId": "cup_deposit_borrow",
      "category": {
        "id": "rtc_001",
        "name": "0.5L Cup",
        "description": "Standard half-liter reusable cup",
        "currencyCode": "HUF"
      }
    }
  ],
  "hybridRevoTokenProducts": [
    {
      "id": "hrtp_001",
      "productId": "beer_500ml",
      "hybridCategory": {
        "id": "cat_001",
        "expirationHours": 48,
        "depositGross": 500,
        "currencyCode": "HUF",
        "revoTokenCategory": {
          "id": "rtc_001",
          "name": "0.5L Cup",
          "description": "Standard half-liter reusable cup",
          "currencyCode": "HUF"
        }
      }
    }
  ]
}

The response is a flat list of products, each carrying the category it maps to.

Field	Description
revoTokenProducts	Products that borrow or return a plain RevoUnion token. Each has an action of BORROW or RETURN and the category it affects.
hybridRevoTokenProducts	Products that issue a hybrid container deposit when purchased. This is the list Hybrid RevoUnion integrations use.

For each entry in hybridRevoTokenProducts:

Field	Description
productId	The product id in your system. Match your basket lines against this.
hybridCategory.id	The category id. Send this as hybridRevoTokenCategoryId when validating a return.
hybridCategory.depositGross	The deposit to charge per container -- and to refund per container returned.
hybridCategory.expirationHours	How long the guest has to return the container.
hybridCategory.currencyCode	Currency of the deposit.
hybridCategory.revoTokenCategory	Optional. Human-readable container details (name, description) for display.

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

Disabled configurations

There is no isEnabled flag on the response. If the organization's configuration is disabled, this endpoint returns 400 with HYBRID_REVO_TOKEN_CONFIGURATION_NOT_ENABLED instead of a payload -- treat that as "skip Hybrid RevoUnion issuance". See Error Handling.

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",
  "sequenceNumber": "2026/000123",
  "categorySummaries": [
    {
      "hybridRevoTokenCategory": {
        "id": "cat_001",
        "expirationHours": 48,
        "depositGross": 500,
        "currencyCode": "HUF",
        "revoTokenCategory": {
          "id": "rtc_001",
          "name": "0.5L Cup",
          "currencyCode": "HUF"
        }
      },
      "activeItemCount": 2,
      "expiresAt": "2026-03-17T14:30:00Z"
    },
    {
      "hybridRevoTokenCategory": {
        "id": "cat_002",
        "expirationHours": 48,
        "depositGross": 300,
        "currencyCode": "HUF",
        "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.)
• Print the sequenceNumber as the human-readable reference for this transaction
• 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,
      "currencyCode": "HUF",
      "revoTokenCategory": {
        "id": "rtc_001",
        "name": "0.5L Cup",
        "currencyCode": "HUF"
      }
    },
    "activeItemCount": 2
  },
  {
    "category": {
      "id": "cat_002",
      "expirationHours": 48,
      "depositGross": 300,
      "currencyCode": "HUF",
      "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,
      "currencyCode": "HUF",
      "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.