Cashless

No cash circulates inside the venue: the wristband carries balance, it is topped up and spent at the bars. This page covers how to read it and, if the organiser authorises you, how to top it up. Scopes: cashless.read for everything read-only, cashless.write to top up (requires manual activation).

All amounts are integers in cents. 2500 is €25.00. The event’s currency is in GET /event.

Reading a wristband

It is addressed by its radio code, NFC or UHF, which is what your application has after a scan:

curl https://api.ventry.es/v1/wristbands/04A2B1C3D4E580 \
  -H "Authorization: Bearer $VENTRY_KEY"

const wristband = await (
  await fetch("https://api.ventry.es/v1/wristbands/04A2B1C3D4E580", {
    headers: { Authorization: `Bearer ${process.env.VENTRY_KEY}` },
  })
).json();

console.log(wristband.balance);  // in cents

wristband = requests.get(
    "https://api.ventry.es/v1/wristbands/04A2B1C3D4E580",
    headers={"Authorization": f"Bearer {os.environ['VENTRY_KEY']}"},
    timeout=10,
).json()

print(wristband["balance"])  # in cents

$wristband = callVentry("GET", "/wristbands/04A2B1C3D4E580");

echo $wristband["balance"];  // in cents

{
  "object": "wristband",
  "id": "6a3d0712a1e963300ee2cc21",
  "nfc": "04A2B1C3D4E580",
  "uhf": "E28068940000501234567890",
  "status": "active",
  "balance": 4750,
  "attendee": { "name": "Ada Lovelace", "anonymous": false },
  "ticket": { "code": "TR-84213-001", "ticket_type": "VIP pass" },
  "allowed_zones": [
    { "id": "6a3d2a67a1e963300ee2c99c", "name": "Venue" },
    { "id": "6a3d2a6ea1e963300ee2c99d", "name": "VIP area" }
  ],
  "valid_days": ["6a3d0512...", "6a3d0518..."],
  "created_at": "2026-06-12T17:20:41.882Z",
  "updated_at": "2026-06-12T22:05:13.119Z"
}

Possible statuses:

`status`	Meaning
`active`	Operational
`blocked`	Blocked by the organiser
`lost`	Reported lost
`released`	Released at the end of the event
`pending_review`	Unresolved double accreditation: cannot spend

Anonymous wristbands — the ones sold at the top-up point with no ticket attached — return attendee.name: null and anonymous: true. They have no identified holder, and the internal name they carry is synthetic.

Negative balance

balance can be negative. It is not a bug on your side: when a terminal charges without connectivity and the sale syncs later, the drink has already been served, and VENTRY would rather record the overdraft than unbalance the till. The overdraft is capped by the event’s policy.

Purchases

curl "https://api.ventry.es/v1/wristbands/04A2B1C3D4E580/transactions?limit=50" \
  -H "Authorization: Bearer $VENTRY_KEY"

{
  "object": "list",
  "data": [
    {
      "object": "transaction",
      "id": "6a3d0911a1e963300ee2ce02",
      "status": "completed",
      "type": "cart",
      "payment_method": "wristband",
      "total": 750,
      "total_base": 682,
      "total_tax": 68,
      "tax_breakdown": [{ "tax_type": "IVA", "rate": 10, "base": 682, "amount": 68 }],
      "items": [
        {
          "product_id": "6a3d2b11a1e963300ee2ca02",
          "name": "Beer",
          "quantity": 2,
          "unit_price": 500,
          "charged_amount": 500,
          "included_quantity": 1
        }
      ],
      "wristband_id": "6a3d0712a1e963300ee2cc21",
      "day_id": "6a3d0512...",
      "device_id": "6a3d0620a1e963300ee2cb99",
      "occurred_at": "2026-06-12T21:14:55.301Z",
      "created_at": "2026-06-12T21:15:02.771Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Note the difference between quantity and charged_amount. In the example two €5.00 beers were served, but one was covered by a drink included in the VIP pass (included_quantity: 1), so only €5.00 was charged to the balance. total is always what was actually charged, not the nominal value of what was served. If you add up unit_price * quantity to reconcile takings, you will book revenue that never existed.

Top-ups and withdrawals

curl "https://api.ventry.es/v1/topups?day=6a3d0512...&direction=topup&limit=200" \
  -H "Authorization: Bearer $VENTRY_KEY"

{
  "object": "list",
  "data": [
    {
      "object": "topup",
      "id": "6a3d0a02a1e963300ee2cf13",
      "direction": "topup",
      "amount": 2000,
      "previous_balance": 2750,
      "new_balance": 4750,
      "payment_method": "card",
      "status": "completed",
      "wristband_id": "6a3d0712a1e963300ee2cc21",
      "day_id": "6a3d0512...",
      "device_id": "6a3d0633a1e963300ee2cba7",
      "occurred_at": "2026-06-12T20:02:19.550Z",
      "created_at": "2026-06-12T20:02:19.812Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

direction: "withdraw" entries are balance refunds to the attendee. amount is always positive; the direction is given by direction.

Topping up

Only if you have cashless.write. Meant for integrators who charge the top-up on their own platform — an online top-up app, for instance — and need to reflect it in VENTRY.

curl -X POST https://api.ventry.es/v1/wristbands/04A2B1C3D4E580/topups \
  -H "Authorization: Bearer $VENTRY_KEY" \
  -H "Idempotency-Key: topup-99312" \
  -H "Content-Type: application/json" \
  -d '{ "amount": 2500 }'

// Call ONLY after your payment gateway has confirmed the charge.
await fetch("https://api.ventry.es/v1/wristbands/04A2B1C3D4E580/topups", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.VENTRY_KEY}`,
    // Derived from the payment, not random: survives a process restart.
    "Idempotency-Key": `topup-${payment.id}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ amount: 2500 }),  // cents
});

# Call ONLY after your payment gateway has confirmed the charge.
requests.post(
    "https://api.ventry.es/v1/wristbands/04A2B1C3D4E580/topups",
    headers={
        "Authorization": f"Bearer {os.environ['VENTRY_KEY']}",
        # Derived from the payment, not random: survives a process restart.
        "Idempotency-Key": f"topup-{payment.id}",
    },
    json={"amount": 2500},  # cents
    timeout=30,
)

<?php
// Call ONLY after your payment gateway has confirmed the charge.
callVentry("POST", "/wristbands/04A2B1C3D4E580/topups", [
    "headers" => [
        // Derived from the payment, not random: survives a process restart.
        "Idempotency-Key: topup-{$payment->id}",
        "Content-Type: application/json",
    ],
    "body" => json_encode(["amount" => 2500]),  // cents
]);

{
  "object": "topup_result",
  "id": "6a3d0b41a1e963300ee2d022",
  "amount": 2500,
  "previous_balance": 4750,
  "new_balance": 7250,
  "replayed": false
}

Charge first, top up after. VENTRY charges nothing: it only adds balance. Call this endpoint once your gateway has confirmed the payment, never before.The movement is recorded with payment method manual and against your API key’s virtual device, so it shows up in the event’s closeout. The organiser has to be able to see it in order to reconcile: you are the one holding the money.

If the wristband does not accept top-ups — it is under review, or released — the response is 422 topup_failed.

Reconciliation

To pull the takings into your own system:

curl "https://api.ventry.es/v1/reports/sales-summary?day=6a3d0512..." \
  -H "Authorization: Bearer $VENTRY_KEY"

{
  "object": "sales_summary",
  "day_id": "6a3d0512...",
  "currency": "EUR",
  "sales": {
    "count": 4182,
    "total": 3187450,
    "total_tax": 289768,
    "by_method": { "wristband": 2984200, "card": 203250 }
  },
  "topups": {
    "count": 1904,
    "total": 3402000,
    "by_method": { "cash": 1201000, "card": 2151000, "manual": 50000 }
  },
  "withdrawals": { "count": 112, "total": 89400 },
  "unconsumed_balance": 124600
}

These figures come from the same function that feeds the closeout in the VENTRY dashboard, so they match exactly what the organiser sees.

Always group by occurred_at

A sale made at 22:00 without connectivity and synced at 02:00 carries an occurred_at of 22:00. If you group by created_at, Friday night’s takings will appear split between Friday and Saturday.

Overlap the window when syncing

For the same reason: go back a few hours from your last pass and deduplicate by id. See Pagination.

unconsumed_balance is not revenue

It is the balance left unspent on wristbands. Some will be refunded to attendees and some will not. Do not add it to sales.

If your key is limited to specific days

GET /reports/sales-summary without day returns 422 day_required. This is deliberate: silently handing you a truncated total would look like the whole event’s total and would not be. Request each day separately.

Get started

Core concepts

Use cases

Coming soon

Reading a wristband

Negative balance

Purchases

Top-ups and withdrawals

Topping up

Reconciliation

​Reading a wristband

​Negative balance

​Purchases

​Top-ups and withdrawals

​Topping up

​Reconciliation

Reading a wristband

Negative balance

Purchases

Top-ups and withdrawals

Topping up

Reconciliation