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,
  "promo_balance": 500,
  "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.

Paid balance and gifted balance

A wristband carries two balances:

balance: what the attendee paid. The only one refunded at the end.
promo_balance: what the organiser gifted (courtesy credit and top-up bonuses). Spent at the bar like the other one, but never refunded.

What can be spent is the sum of both. If you show a balance to the attendee, show both separately: “€55, of which €5 is a non-refundable gift”.

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 online 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.

Top-up bonuses

The organiser can gift balance for topping up: “top up €50 and get €5 free”. Rules are set up in the dashboard, and the highest tier reached applies; if several rules match, the most generous one wins. The gift goes to promo_balance. To work well, the attendee has to see the gift before paying:

Ask for the gift of the amounts you offer. code (ticket or wristband) applies the per-person cap, if the rule has one.

curl "https://api.ventry.es/v1/topup-bonuses/quote?amounts=2000,5000&code=TR-84213-001" \
  -H "Authorization: Bearer $VENTRY_KEY"

{
  "object": "topup_bonus_quote",
  "data": [
    {
      "amount": 2000,
      "bonus_amount": 100,
      "rule": { "id": "6a3d4c11a1e963300ee2d101", "name": "Top up more" },
      "next": { "amount": 5000, "bonus_amount": 500 }
    },
    {
      "amount": 5000,
      "bonus_amount": 500,
      "rule": { "id": "6a3d4c11a1e963300ee2d101", "name": "Top up more" },
      "next": null
    }
  ]
}

next is the next tier that improves the gift, to encourage a bigger top-up: “add €30 and get €5 free”.

Show it next to the amount and charge.
When topping up, send what you showed and when:
{ "amount": 5000, "bonus_amount": 500, "bonus_rule": "6a3d4c11a1e963300ee2d101", "granted_at": "2026-06-01T10:15:00Z" }
The rule is checked at granted_at, so a top-up paid before the event keeps its gift even if you deliver it after the promotion has ended. At most what the rule allows for that amount is granted; the response tells you how much was given in bonus_amount and leaves the gifted balance in new_promo_balance.

If you hold top-ups to deliver later (for instance, those paid before the event and delivered at check-in), pass them in pending_rules when quoting: one entry per pending top-up with a gift. They count towards the per-person cap, so you never promise a gift that would no longer apply at delivery.

GET /topup-bonuses lists the active rules for the online channel, with their tiers and dates, in case you want to advertise them.

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, "cash": 0, "external_card": 0 }
  },
  "topups": {
    "count": 1904,
    "total": 3402000,
    "by_method": { "cash": 1201000, "card": 2151000, "online": 40000, "manual": 10000 }
  },
  "courtesy": { "count": 35, "total": 70000 },
  "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. topups only contains paid top-ups. Balance given away by the organiser (courtesies, bonuses) goes separately in courtesy: it moves balance, but it is not money received. In GET /topups, each top-up says so in nature.

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

Paid balance and gifted balance

Negative balance

Purchases

Top-ups and withdrawals

Topping up

Top-up bonuses

Reconciliation

​Reading a wristband

​Paid balance and gifted balance

​Negative balance

​Purchases

​Top-ups and withdrawals

​Topping up

​Top-up bonuses

​Reconciliation

Reading a wristband

Paid balance and gifted balance

Negative balance

Purchases

Top-ups and withdrawals

Topping up

Top-up bonuses

Reconciliation