(b) Endpoints iVendNext calls on your service
Part 2 of 4 · What you can use: API endpoints, record types, fields and screens
One row per extension point, from its contract page in contracts/: when it fires, what it sends, what you answer, its time limit and what the cashier or user sees. How the extension points fit together, and how to ask for a new one: chapter 9.
Back: (a) iVendNext endpoints your app callsNext: (c) What a manifest can add
Calls on your service
iVendNext calls your service's address over HTTPS, signed with that retailer's secret, at the moment named. Each cell is the contract page's own words.
| Extension point | When it fires | What it sends | What you answer | Time limit | What the cashier or user sees |
|---|---|---|---|---|---|
| Desk action | “It fires when a user presses it. The server then re-checks everything the button showed on the record as SAVED (never the form's copy)” | “Only then does it send exactly the declared fields to your service and judge your answer.” | “The answer — HTTP 2xx, a JSON object of at most 64 KB: a message” |
“3 seconds to answer unless the subscription allows more, 10 at most. No retry.” | “down, slow or unreachable — "⟨label⟩ did not answer in time. Check the record before you try again."” |
| Document check | “It fires when the document is submitted, from every door: the iVendNext Desk form or list, a data import, and the API.” | “what is sent with every call — the user's login (usually an email address) and language, the company, the record's type and name — the fields that leave the shop” | “The answer — HTTP 2xx, a JSON object of at most 64 KB, one of five:” … “allow” … “refuse” … “ask” … “approve” … “fill” |
“the time to answer (3 seconds unless raised, at most 10)” | “allow_and_flag (the default: the submit goes on and the log row is flagged), refuse (did not answer, so this document can't be submitted yet), or ask (did not answer. Submit anyway?)” |
| Partner capture | “On scan — when the cashier scans an item your filter names (its item group, a group below it, or an item field that is set), after the item is found and before its line goes on the sale.” | “line: its item_code, item_group, quantity, unit, batch, serial and the code scanned.” | “allow (nothing shown), confirm (a beep and a yes / no;” | “on scan or a quantity change 1.5 seconds unless raised, 3 at most · on customer add or select 3 seconds unless raised, 10 at most” | “"⟨label⟩ did not answer. The item can't be added until it does."” |
| Partner check | “It fires when the cashier presses Pay, before the payment sheet opens (stage: "sale"); before the refund choices open on every refund the till pays (stage: "return")” |
“The numbers are the server's, never the till's echo. Money is a whole number of minor units with the currency's own digits (currency_exponent: 2 for AED, 3 for KWD, 0 for JPY); quantity is in thousandths.” |
“allow it, allow it without some tenders, refuse it, ask the cashier a question, or call a manager.” | “3 seconds unless raised, at most 10 · at most 3 checks per POS Profile, 10 seconds together” | “"⟨label⟩ did not answer. This sale can't be paid until it does. Try again, or get a manager."” |
| Partner fulfil | “iVendNext writes one Pending record per sold line inside the sale's own booking, then asks you after the booking commits.” | “the sale's number, the store, the till's POS Profile, the company, the currency, the language, the customer's id, and the line's item code, item group, unit, face value and amount” | “{"verdict": "issued", "ref": "GZ-77120", "lines": ["PIN 4821 0937 5521", "Valid until 16 Oct 2027"]}” | “a time to answer (5 seconds unless raised, at most 10)” | “The cashier sees Waiting for ⟨your label⟩'s code for ⟨item⟩, with Try again and Print without it.” |
| Partner page | “It fires when the cashier presses the page's key on the till, or when a Desk user opens the page” | “Your page learns who is looking at what from a signed, one-time, five-minute context in its address” | “on the till your server may answer once — a message, Sale Attribute rows, or both — which the cashier confirms like any till key” | “a page that has not loaded in 10 seconds” | “A page that does not load in 10 seconds shows "⟨label⟩ isn't answering." with Close; nothing is added to the sale.” |
| Payer | “On a sale to a named customer the cashier presses Payer; we ask your service which covers the customer holds (covers) and the cashier picks one (the only one is taken).” |
“We send the customer's record name, the date, the store, the POS Profile and the cashier.” | “you answer each line's two shares: yours and the customer's (coverage)” |
“the time to answer (at most 5 seconds; 3 when left empty)” | “a service that does not answer in time, errs, fails its signature or answers wrongly means no cover: "⟨label⟩ cannot be reached: the customer can pay it all, or hold the sale."” |
| The iVendNext Remote Gateway Contract | “Every call is a signed POST to https://<connector>/paygw/1/<verb>” |
“{v, site, reference, merchant, amount_minor, currency, currency_exponent, rail, device, payer{phone,email,name,party} (may be empty), payer_code?}” |
“An Answer (authorise, status): {v, site, reference, outcome, amount_minor?, currency, auth_ref?, correlation_id?, capture_state?, reason?, exists?, instrument?}” |
“every rail's authorise has the one 60 s deadline.” |
“A preview that times out, is refused or is malformed dims the wallet at the till for that sale; it never raises at the till.” |
| Remote till key | “It fires on a press, and only then: never before payment, never at booking, never on a schedule.” | “When the cashier presses it, the iVendNext POS server sends your service a read-only picture of the sale in progress.” | “You answer with a message for the cashier, Sale Attribute rows for the sale, values for its lines (Transaction Item Attributes), or any of them together.” | “time to answer 3 seconds unless raised, at most 10” | “"⟨label⟩ did not answer in time. Nothing was added to the sale."” |
| Wallet extension point | “The cashier taps the wallet's tile with a customer on the sale, sees the balance and the most this sale may use” | “{v, customer, customer_name, amount_due_minor, currency, currency_exponent, store, sale_ref, lang}” |
“{eligible, balance_minor, max_redeemable_minor, label, currency, otp_required, reason} within 3 s” |
“within 3 s” | “A wallet that cannot be used is dimmed with its reason ("Wallet isn't installed on this site.", "Add the customer first."), never hidden; a wallet that does not answer its preview says so in the opened sheet.” |
| Webhooks | “For a booked sale, that is Sales Invoice and POS Invoice on Submit” | “a body that names the record and when it changed, and nothing more” | none stated | none stated | none stated |
| The connect, after an install | “the chain's site connects by itself once it is installed” | “it sends your service its library key, its address and the secrets the install made” | none stated | none stated | none stated |
Declared, not called
Nothing calls your service at run time. Some you declare as data in your manifest (save rules, field rules, list marks, register books, a fiscal reader, a sandboxed price module); some are records or settings the retailer makes in Desk (a scan source, a label layout, the receipt's lines); the print readers are what a print format may call; and the event feed, the open check and the station ticket are calls your app makes (part a). Each contract page says which. Each cell is the contract page's own words.
| Extension point | What you declare | When it applies | What the cashier or user sees |
|---|---|---|---|
| Event feed | “List the feed under registered_applications in your manifest: one feed per app, with every record type it follows in its events.” |
“The engine writes one event per document step a change runs, per registered application that follows that record type, after the change commits (a background job, so seconds later).” | “you pull, so a service that is down simply stops pulling. Your events wait, undone, for as long as you are away.” |
| Field rules | “Hide a field nobody uses, relabel it in the shop's own word, require it on a new customer, or show up to three more Item fields and three more Customer fields” | “They fire when the till lights up: the rules ride the theme the till reads at boot, and each screen asks them as it draws.” | “The new-customer sheet has no email field, and adding a customer without a phone at the till is refused with "Phone is required here."” |
| Fiscal reader | “A Retail Fiscal Reader tells the POS which POS Invoice fields hold that result and what each status value means, so a new country needs no release.” | “It fires when a submitted sale changes (the sale's own change hook, after every app's submit), and again whenever the till re-reads a sale that is still waiting” | “Down: the sale waits PENDING and the receipt is held.” |
| Label layout | “A Retail Label Layout is data: HTML with placeholders from a closed list.” | “It fires when the cashier presses Print label on an item's card or on a basket line (phone, counter and tablet alike)” | “The till fills it on the server and opens it in the device's own print dialog, so it prints on any printer the phone, tablet or counter can already reach.” |
| List mark | “A coloured label on a row of a shop's Desk list, shown when the row's values say so” | “The marks travel with the user's boot info (read at each Desk page load; the declarations themselves are one cached read)” | “to every Desk user who may read the record type — and only the marks whose every condition field the user may read.” |
| Open check | “Every verb is a call on the partner API: /api/method/ivendnext_mpos.api.v1.<verb>, POST (the two reads take GET too).” |
“The register's Table Service switch (POS Profile, off by default) turns the whole thing on.” | “The till's own floor reads floor_status again on each message, polls every 30 seconds while its live link is down, and says "Not live. Last updated 20:41." after 90 seconds without one.” |
| Pricing extension point | “answered by your sandboxed module (a WebAssembly function, see the partner check's section 6 and the Wasm kit). It may only take money off a line.” | “on the iVendNext POS server, after every promotion (item-level and whole-sale), on the promotion-adjusted line, before the line's tax is worked out” | “the basket line names it beside the promotion, "Member 5% −R 5.00", on the phone, the counter and the tablet” |
| Print template readers | “Two readers a print template may call do that, with the rights of the person viewing the print” | “Both readers read as the person viewing the print, the way a Desk list does” | “A refused call answers an empty list (or nothing) and the print renders.” |
| Receipt: the shop's own lines, WhatsApp, a checked layout | “Lines under the store's name (an address, a tax number, a slogan) and lines at the very end (a returns policy, a thank-you in a second language).” | “They print on every receipt of that register, on every print route and in the Print sheet's preview, in every frame.” | “The shipped receipts** print the register's header and footer” |
| Register books | “A book says which items it takes, which movements enter it, how its lines are numbered and corrected, and which columns it prints, with the source of each.” | “Each movement of an item a book takes writes one Retail Register Line per book it enters, per document row, per batch, in the same save as the document” | “the till checks before the tender and stops a basket that would go below zero, naming who settles it (a count of the book by its count role).” |
| Save rules | “A Retail Save Rule record names the record type (and the table, for a rule on rows), one of ten kinds, and whether a broken rule refuses the save or flags it to the Sales to review report.” | “It fires at every save of that record type — a Desk form, an import and an API write alike” | “pattern: "⟨Field⟩: use letters and digits only."” |
| Scan source | “declares that table once, and the till's scan finds the unit: its item, its batch, its serial, and whether it can be sold.” | “It fires only on a miss: an item barcode, a serial or a batch is found exactly as before and no source is read.” | “A source that cannot be read is logged and skipped, so a misconfigured table can cost a Not found, never a sale.” |
| Station ticket | “Each is a call on the partner API, /api/method/ivendnext_mpos.api.v1.<name>, under the rights of the user your app signs in as.” |
“When a till presses Send, each kitchen station gets its own ticket” | “There is no cursor to lose: every read is the whole board, so a screen that dropped its connection reads it again and has caught up.” |
Back: (a) iVendNext endpoints your app callsNext: (c) What a manifest can add