Virtual wallets

If your organizer account has the virtual wallets feature active, you can use the methods on this page to implement virtual transactions for your attendees.

Note

Before calling any of the methods on this page, you must obtain a valid authorization token. To learn about obtaining an authorization token, please read the Authentication section.

Create or credit virtual wallet

This method creates or credits a virtual wallet with a specified monetary amount.

HTTP request

POST https://l.oveit.com/api/wallet/credit

Request parameters

Parameter	Description
`token`	A valid access token, obtained in the Authentication step.
`event_id`	The unique event ID. Please see the Event data page for information on obtaining event IDs.
`ticket_code`	(Optional, if the `rfid_code` parameter is used) The unique ticket code. This can be obtained by scanning the ticket's barcode or QR code. It is also listed in plain text on the ticket. Either this parameter or the `rfid_code` parameter below must be present in the request.
`rfid_code`	(Optional, if the `ticket_code` parameter is used) The string tag stored on an RFID chip. To learn about associating tickets with RFID tags, read the section on RFID section
`amount`	The amount to credit the wallet with.
`currency`	The currency for the amount above.
`meta`	A JSON object describing the credit origin and, for voids, linking back to the original debit. See the Credit transaction meta object section below.

Response example

{
    "transaction": {
        "id": 3877,
        "author_id": 1,
        "amount": "5.50",
        "currency": "USD",
        "type": "credit",
        "date": "2017-10-24T07:30:45+00:00",
        "canceled_at": null
    },
    "balance": [
        {
            "amount": "10.50",
            "currency": "USD"
        }
    ]
}

Credit transaction meta object

The meta parameter on a credit transaction is a JSON object that describes the origin of the credit. Unlike the debit meta (which captures full POS receipt data), the credit meta is lightweight — credits represent money flowing into the wallet via top-ups or, in rare cases, voids of previous debit transactions.

Field reference

Top-level fields

Field	Type	Required	Description
`source`	string	Yes	Origin of the credit. One of: `"online_topup"`, `"box_office_topup"`, `"import"`, `"pos_void"`, `"manual"`.
`device`	string	No	Device or terminal identifier. Required when `source` is `"box_office_topup"` or `"pos_void"`. Omit for online / import / customer_order credits.
`void`	object	No	Present only when this credit reverses a previous debit transaction. See void fields below.
`paymentMethods`	array	No	How the top-up was funded. One entry per payment method used. When the payment is split across methods, include two or more objects. See payment method fields below.
`note`	string	No	Free-text note from the operator or POS (e.g. `"Customer complaint — partial refund"`, `"Manager override"`).

Payment method fields

Field	Type	Required	Description
`type`	string	Yes	Payment method identifier (e.g. `"cash"`, `"card"`, `"online_card"`).
`amount`	string	Yes	Amount paid with this method, pre-rounded to 2 decimal places (e.g. `"60.00"`).

Void fields (the void object, present only for reversal credits)

Field	Type	Required	Description
`debitExternalId`	string	Yes	The `externalId` of the original debit transaction being voided (matches the debit's `meta.externalId`).
`debitTransactionId`	number	No	Oveit's internal transaction ID of the voided debit, if known by the caller.
`reason`	string	No	Reason for the void (e.g. `"wrong_order"`, `"customer_complaint"`, `"duplicate"`, or free text).

Source values

Value	When to use
`online_topup`	Guest topped up via the online top-up page (card payment processed by Mobilpay, Shift4, etc).
`box_office_topup`	Cashier topped up the wallet at a box office terminal.
`import`	Credit was created via a bulk import (CSV or API).
`pos_void`	An external POS is reversing a previous debit transaction. The `void` object must be present.
`manual`	A manual adjustment by an operator (e.g. compensation, correction).

Example 1 — Online top-up

Guest tops up €100.00 via the online payment page.

{
    "meta": {
        "source": "online_topup",
        "paymentMethods": [
            { "type": "online_card", "amount": "100.00" }
        ]
    }
}

Example 2 — Box Office top-up with cash

Cashier tops up €50.00 in cash at the entrance.

{
    "meta": {
        "source": "box_office_topup",
        "paymentMethods": [
            { "type": "cash", "amount": "50.00" }
        ],
        "device": "POS 1 Entrance"
    }
}

Example 3 — Split payment top-up

Cashier tops up €100.00 split across cash and card.

{
    "meta": {
        "source": "box_office_topup",
        "paymentMethods": [
            { "type": "cash", "amount": "60.00" },
            { "type": "card", "amount": "40.00" }
        ],
        "device": "POS 1 Entrance"
    }
}

Verification:

Payment methods total: 60.00 + 40.00 = 100.00 ✓ (must match request amount)

Example 4 — POS void (reversing a debit)

An external POS voided order 1001 (a €31.50 debit). The POS sends a credit for the same amount to restore the wallet balance.

{
    "meta": {
        "source": "pos_void",
        "device": "POS 1 Pool",
        "void": {
            "debitExternalId": "1001",
            "reason": "wrong_order"
        }
    }
}

Example 5 — Import credit

Credit created as part of a bulk wallet import.

{
    "meta": {
        "source": "import"
    }
}

Example 6 — Manual operator credit with note

Operator credits €15.00 as compensation for a service issue.

{
    "meta": {
        "source": "manual",
        "note": "Compensation for X reason"
    }
}

Important notes

The credited amount is stored on the transaction itself (amount request parameter / transaction.amount in the response), not in meta.
When paymentMethods is present, the sum of all paymentMethods[].amount values must equal the request amount.
For a single payment method, send one object in paymentMethods. For split payments, send two or more.
The void object is only used when source is "pos_void". It links the credit back to the original debit transaction via debitExternalId.
Unlike debit meta, credit meta does not include products, vatSummary, subTotal, or total. Credits are not fiscally decomposed — VAT handling for voids is managed by the POS's own fiscal reversal.
The device field is optional but should be included for credits originating from a physical terminal (box_office_topup, pos_void).
The note field is optional. Use it for operator-facing context that does not fit the structured fields.

Debit virtual wallet

This method debits a virtual wallet with a specified monetary amount.

HTTP request

POST https://l.oveit.com/api/wallet/debit

Request parameters

Parameter	Description
`token`	A valid access token, obtained in the Authentication step.
`event_id`	The unique event ID. Please see the Event data page for information on obtaining event IDs.
`ticket_code`	(Optional, if the `rfid_code` parameter is used) The unique ticket code. This can be obtained by scanning the ticket's barcode or QR code. It is also listed in plain text on the ticket. Either this parameter or the `rfid_code` parameter below must be present in the request.
`rfid_code`	(Optional, if the `ticket_code` parameter is used) The string tag stored on an RFID chip. To learn about associating tickets with RFID tags, read the section on RFID section
`amount`	The amount to debit the wallet with. Must be a positive value.
`currency`	The currency for the amount above.
`meta`	A JSON object containing the transaction details: products, discounts and VAT breakdown. See the Transaction meta object section below.

Note

The amount parameter must have a positive value, even for the debit method.

Response example

See the credit method above.

Transaction meta object

The meta parameter is a JSON object that captures the full receipt data of a POS transaction. All monetary values must be pre-rounded to 2 decimal places by the POS system.

Field reference

Top-level fields

Field	Type	Required	Description
`externalId`	string	Yes	Transaction identifier within the POS system.
`products`	array	Yes	Array of product line items. See product fields below.
`discounts`	array	No	Order-level discounts. Each object has `name` (string) and `amount` (number). Omit if no order-level discounts were applied.
`tip`	object	No	Optional tip / service charge. See tip fields below. Omit entirely when no tip was given.
`vatSummary`	array	Yes	One entry per distinct VAT rate. Each object has `vatRate` (number), `net` (number), and `vat` (number). These are the post-discount fiscal amounts as computed by the POS.
`subTotal`	number	Yes	Sum of all product final prices (after item-level discounts, before order-level discounts).
`total`	number	Yes	Final charged amount (after all discounts, plus tip if present).
`device`	string	Yes	POS device identifier.

Product fields

Field	Type	Required	Description
`name`	string	Yes	Product display name.
`externalId`	string	Yes	Product identifier (SKU) within the POS system.
`quantity`	number	Yes	Number of units.
`unitPrice`	number	Yes	Price per single unit (VAT-inclusive).
`total`	number	Yes	Line total before any discount, equal to `unitPrice × quantity` (VAT-inclusive).
`discounts`	array	No	Item-level discounts. Each object has `name` (string) and `amount` (number). Omit if no discounts were applied to this product.
`vatRate`	number	Yes	VAT rate in percentage points (e.g. `9.00` means 9%).

Tip fields

Field	Type	Required	Description
`name`	string	Yes	Display label (e.g. `"Tip"`, `"Service Charge"`, `"Gratuity"`).
`amount`	number	Yes	Tip amount, VAT-inclusive, positive, pre-rounded to 2 decimal places.
`vatRate`	number	Yes	VAT rate in percentage points (e.g. `9.00`). Use `0` for discretionary tips outside VAT scope.

Verification rules

Use these rules to validate that a meta object is internally consistent:

Rule	Formula
Product total	`unitPrice × quantity = total`
Product final price	`total − sum(product.discounts[].amount)`
Sub Total	`sum of all product final prices = subTotal`
Total	`subTotal − sum(order discounts[].amount) + (tip.amount or 0) = total`
VAT Summary	`sum(vatSummary[].net) + sum(vatSummary[].vat) = total`

VAT and discount calculation

When building vatSummary, keep these two rules in mind:

Compute VAT per rate bucket, not per product. Add up all post-discount gross amounts that share the same vatRate, then derive net and vat for that group. Rounding each product separately can shift net/vat by a cent even when total is correct.
Split order-level discounts across VAT rates. When an order discount covers products at different rates, allocate it in proportion to each rate's share of the pre-discount gross. See Example 4: the €5.00 loyalty discount becomes €3.05 off 9% products and €1.95 off 21% products.

Example 1 — Simple: no discounts, single VAT rate

Two products, both at 9% VAT, no discounts.

{
    "meta": {
        "externalId": "1001",
        "products": [
            {
                "name": "Soft Drink 0.33L",
                "externalId": "211113267",
                "quantity": 1,
                "unitPrice": 3.50,
                "total": 3.50,
                "vatRate": 9.00
            },
            {
                "name": "Angus Cheeseburger",
                "externalId": "345000112",
                "quantity": 1,
                "unitPrice": 28.00,
                "total": 28.00,
                "vatRate": 9.00
            }
        ],
        "vatSummary": [
            { "vatRate": 9.00, "net": 28.90, "vat": 2.60 }
        ],
        "subTotal": 31.50,
        "total": 31.50,
        "device": "POS 1 Pool"
    }
}

Verification:

Product final prices: 3.50 + 28.00 = 31.50
subTotal = 31.50 ✓
total = 31.50 (no discounts) ✓
VAT check: 28.90 + 2.60 = 31.50 ✓

Example 2 — Two VAT rates, no discounts

Three products across two VAT rates (9% and 21%), no discounts.

{
    "meta": {
        "externalId": "1002",
        "products": [
            {
                "name": "Soft Drink 0.33L",
                "externalId": "211113267",
                "quantity": 1,
                "unitPrice": 3.50,
                "total": 3.50,
                "vatRate": 9.00
            },
            {
                "name": "Angus Cheeseburger",
                "externalId": "345000112",
                "quantity": 1,
                "unitPrice": 28.00,
                "total": 28.00,
                "vatRate": 9.00
            },
            {
                "name": "Premium Red Wine 750ml",
                "externalId": "567000234",
                "quantity": 1,
                "unitPrice": 12.00,
                "total": 12.00,
                "vatRate": 21.00
            }
        ],
        "vatSummary": [
            { "vatRate": 9.00, "net": 28.90, "vat": 2.60 },
            { "vatRate": 21.00, "net": 9.92, "vat": 2.08 }
        ],
        "subTotal": 43.50,
        "total": 43.50,
        "device": "POS 1 Pool"
    }
}

Verification:

Product final prices: 3.50 + 28.00 + 12.00 = 43.50
subTotal = 43.50 ✓
total = 43.50 (no discounts) ✓
VAT check: 28.90 + 2.60 + 9.92 + 2.08 = 43.50 ✓

Example 3 — Item-level discount, single VAT rate

One product has a 10% discount. Both products are at 9% VAT.

{
    "meta": {
        "externalId": "1003",
        "products": [
            {
                "name": "Fresh Orange Juice 1L",
                "externalId": "211113267",
                "quantity": 2,
                "unitPrice": 4.00,
                "total": 8.00,
                "discounts": [
                    { "name": "Happy Hour 10%", "amount": 0.80 }
                ],
                "vatRate": 9.00
            },
            {
                "name": "Margherita Pizza",
                "externalId": "567000234",
                "quantity": 1,
                "unitPrice": 32.00,
                "total": 32.00,
                "vatRate": 9.00
            }
        ],
        "vatSummary": [
            { "vatRate": 9.00, "net": 35.96, "vat": 3.24 }
        ],
        "subTotal": 39.20,
        "total": 39.20,
        "device": "POS 1 Pool"
    }
}

Verification:

Product final prices: (8.00 − 0.80) + 32.00 = 7.20 + 32.00 = 39.20
subTotal = 39.20 ✓
total = 39.20 (no order-level discounts) ✓
VAT check: 35.96 + 3.24 = 39.20 ✓

Example 4 — Item and order discounts, two VAT rates

One product has an item-level discount, plus an order-level loyalty discount. Products span two VAT rates (9% and 21%).

{
    "meta": {
        "externalId": "1004",
        "products": [
            {
                "name": "Fresh Orange Juice 1L",
                "externalId": "211113267",
                "quantity": 2,
                "unitPrice": 4.00,
                "total": 8.00,
                "discounts": [
                    { "name": "Happy Hour 10%", "amount": 0.80 }
                ],
                "vatRate": 9.00
            },
            {
                "name": "Premium Red Wine 750ml",
                "externalId": "345000112",
                "quantity": 1,
                "unitPrice": 25.00,
                "total": 25.00,
                "vatRate": 21.00
            },
            {
                "name": "Margherita Pizza",
                "externalId": "567000234",
                "quantity": 1,
                "unitPrice": 32.00,
                "total": 32.00,
                "vatRate": 9.00
            }
        ],
        "discounts": [
            { "name": "Loyalty Reward", "amount": 5.00 }
        ],
        "vatSummary": [
            { "vatRate": 9.00, "net": 33.17, "vat": 2.98 },
            { "vatRate": 21.00, "net": 19.05, "vat": 4.00 }
        ],
        "subTotal": 64.20,
        "total": 59.20,
        "device": "POS 1 Pool"
    }
}

Verification:

Product final prices: (8.00 − 0.80) + 25.00 + 32.00 = 7.20 + 25.00 + 32.00 = 64.20
subTotal = 64.20 ✓
total = 64.20 − 5.00 = 59.20 ✓
Order discount split: €3.05 from 9% products, €1.95 from 21% products (proportional to pre-discount gross) ✓
VAT check: 33.17 + 2.98 + 19.05 + 4.00 = 59.20 ✓

Example 5 — With tip, single VAT rate

Two products at 9% VAT plus a tip. The POS folds the tip's fiscal contribution into vatSummary.

{
    "meta": {
        "externalId": "1005",
        "products": [
            {
                "name": "Soft Drink 0.33L",
                "externalId": "211113267",
                "quantity": 1,
                "unitPrice": 3.50,
                "total": 3.50,
                "vatRate": 9.00
            },
            {
                "name": "Angus Cheeseburger",
                "externalId": "345000112",
                "quantity": 1,
                "unitPrice": 28.00,
                "total": 28.00,
                "vatRate": 9.00
            }
        ],
        "tip": {
            "name": "Tip",
            "amount": 5.00,
            "vatRate": 9.00
        },
        "vatSummary": [
            { "vatRate": 9.00, "net": 33.49, "vat": 3.01 }
        ],
        "subTotal": 31.50,
        "total": 36.50,
        "device": "POS 1 Pool"
    }
}

Verification:

Product final prices: 3.50 + 28.00 = 31.50
subTotal = 31.50 ✓
total = 31.50 + 5.00 (tip) = 36.50 ✓
VAT check: 33.49 + 3.01 = 36.50 ✓

Important notes

All monetary amounts (unitPrice, total, amount, net, vat, subTotal, total) must be rounded to 2 decimal places by the POS before sending. Oveit does not round or recompute these values.
The products[].discounts and top-level discounts fields are optional. Omit them entirely when no discounts are applied.
The tip field is optional. Omit it entirely when no tip was given. When present, the tip's VAT contribution must already be included in vatSummary (merged into the matching rate bucket).
vatSummary must reflect the post-discount fiscal amounts. The sum of all net and vat values must equal total.
Compute net and vat per VAT rate bucket (group products by vatRate), not per individual product line.
Split order-level discounts across VAT rates in proportion to each rate's pre-discount gross.
When multiple VAT rates are present, the settlement receipt will display a letter marker (A, B, C…) next to each product, assigned in ascending order of VAT rate.

Withdraw funds from wallet

The withdraw method is almost identical to the debit method above. However, unlike debit transactions, which are meant to be created when the attendee makes a purchase at the event, withdrawal transactions should be created when the attendee withdraws the money that is left in their wallet.

So, while the debit and withdraw methods serve the same purpose from the point of view of the wallet itself (that is, they lower the balance available for other transactions), from a reporting point of view debit transactions represent money that should go to vendors at the event, while withdraw transactions represent money that the attendee is cashing in.

HTTP request

POST https://l.oveit.com/api/wallet/withdraw

Request parameters

Parameter	Description
`token`	A valid access token, obtained in the Authentication step.
`event_id`	The unique event ID. Please see the Event data page for information on obtaining event IDs.
`ticket_code`	(Optional, if the `rfid_code` parameter is used) The unique ticket code. This can be obtained by scanning the ticket's barcode or QR code. It is also listed in plain text on the ticket. Either this parameter or the `rfid_code` parameter below must be present in the request.
`rfid_code`	(Optional, if the `ticket_code` parameter is used) The string tag stored on an RFID chip. To learn about associating tickets with RFID tags, read the section on RFID section.
`currency`	The currency of the virtual wallet balance section to completely withdraw.

Note

Please note the lack of an amount parameter. When calling the withdraw method, all funds for the specified currency are withdrawn from the wallet.

Response example

{
    "transaction": {
        "id": 3883,
        "author_id": 1,
        "amount": "-100.00",
        "currency": "USD",
        "type": "withdraw",
        "date": "2017-10-24T07:55:23+00:00",
        "canceled_at": null
    },
    "balance": [
        {
            "amount": "0.00",
            "currency": "USD"
        }
    ]
}

Cancel a transaction

Use this method to cancel a previous transaction.

HTTP request

POST https://l.oveit.com/api/wallet/cancel

Request parameters

Parameter	Description
`token`	A valid access token, obtained in the Authentication step.
`ticket_code`	(Optional, if the `rfid_code` parameter is used) The unique ticket code. This can be obtained by scanning the ticket's barcode or QR code. It is also listed in plain text on the ticket. Either this parameter or the `rfid_code` parameter below must be present in the request.
`rfid_code`	(Optional, if the `ticket_code` parameter is used) The string tag stored on an RFID chip. To learn about associating tickets with RFID tags, read the section on RFID section
`id`	The unique transaction ID. The transaction IDs are part of the response for all the methods above.

Get virtual wallet balance

This method returns the balance and transaction history for an individual wallet.

HTTP request

POST https://l.oveit.com/api/wallet/balance

Request parameters

Parameter	Description
`token`	A valid access token, obtained in the Authentication step.
`ticket_code`	(Optional, if the `rfid_code` parameter is used) The unique ticket code. This can be obtained by scanning the ticket's barcode or QR code. It is also listed in plain text on the ticket. Either this parameter or the `rfid_code` parameter below must be present in the request.
`rfid_code`	(Optional, if the `ticket_code` parameter is used) The string tag stored on an RFID chip. To learn about associating tickets with RFID tags, read the section on RFID section

Response example

{
    "balance": [
        {
            "amount": "125.00",
            "currency": "USD"
        },
        {
            "amount": "50.00",
            "currency": "EUR"
        }
    ],
    "transactions": [
        {
            "id": 1,
            "author_id": 509,
            "amount": "200.00",
            "currency": "USD",
            "type": "credit",
            "date": "2017-06-14T08:35:03+00:00",
            "canceled_at": null
        },
        {
            "id": 2,
            "author_id": 509,
            "amount": "50.00",
            "currency": "EUR",
            "type": "credit",
            "date": "2017-06-14T08:37:03+00:00",
            "canceled_at": null
        },
        {
            "id": 3,
            "author_id": 510,
            "amount": "-50.00",
            "currency": "USD",
            "type": "debit",
            "date": "2017-06-14T08:37:10+00:00",
            "canceled_at": null
        },
        {
            "id": 4,
            "author_id": 510,
            "amount": "-25.00",
            "currency": "USD",
            "type": "debit",
            "date": "2017-06-14T08:37:11+00:00",
            "canceled_at": null
        }
    ]
}

Note

The balance response property is an array of objects. Each object represents the balance for each currency you have recorded transactions in.
The amount property has a negative value for debit transactions.
The balance is also returned as part of the response for any of the other methods in this section.

List vendor products

This method lists the products available for the logged in vendor for a particular event. This method can only be called with an authorization token belonging to a vendor user.

HTTP Request

POST https://l.oveit.com/api/wallet/products

Request parameters

Parameter	Description
`token`	A valid access token, obtained in the Authentication step.
`event_id`	The event the products are associated with.

Response example

{
    "products": [
        {
            "name": "Beer",
            "price": "2.00",
            "currency": "USD"
        },
        {
            "name": "Cheeseburger",
            "price": "10.50",
            "currency": "USD"
        }
    ]
}