Payments & top-ups at the counter

Hand it to an agent

This prompt briefs an AI coding agent to implement the entire recipe against the live docs — authentication, every endpoint, and webhooks.

Build an Ewity App that sells <digital service, e.g. mobile top-ups> at the POS counter.

Setup: Ewity app with API key <EWITY_APP_KEY>, approved scopes r/create-bill + r/read-customer + r/history-bill, webhook signing secret <whsec_…>, App UI URL configured. API base https://api.ewitypos.com/apps-v1 with headers Authorization: Bearer <EWITY_APP_KEY> and X-Ewity-Store: <store_id>. Docs: https://ewity-api.readme.io/docs/building-apps, https://ewity-api.readme.io/docs/apps-webhooks; App UI protocol via the in-ewity-app-ui recipe prompt.

1) Webhook receiver (signature-verified): app.installed → provision a merchant account with a float balance keyed by install.store_id; app.uninstalled → freeze it.
2) App UI endpoint: verify X-Ewity-Signature + X-Ewity-Context on every request. Tabs: "Sell" (Form: customer number, amount/product select; submit action_id sell), "Transactions" (Table of this store's sales from your DB, newest first), "Balance" (DetailCard with float balance + a modal Form to submit a bank-transfer top-up reference for review).
3) Fulfilment handler for action sell: validate the float covers it, call <provider API>, deduct float, persist the transaction, then record the sale in Ewity with POST /sales/bills (one line for the service at the amount sold) so the merchant's reports and register stay correct. Respond {"toast":{"tone":"success","message":"<n> topped up"},"refresh":true}; on provider failure return a clear error message and do not bill.
4) Reliability: idempotency key per sell action (dedupe double-clicks), a retry queue for bills that failed to record after fulfilment, and a daily reconciliation report per store (fulfilled vs billed).

…or follow the build, step by step

1. 1

   Create the app & request scopes

   Selling at the counter needs bill-writing rights.

   • Request `r/create-bill` (record the sale), `r/read-customer` (attach the sale to a customer when useful) and `r/history-bill`. Set the category to Payments.
   • If merchants need an account on your platform (float balance, commission account), configure a Connect URL — Ewity collects the pairing code at install and every install arrives pre-linked to an account on your side.

   Read the docs for this step
2. 2

   The sell flow, inside the POS

   A Form the cashier fills; an app_action your backend fulfils.

   • GET{app_ui_url}?page=homeServe the sell screen
   • POST{app_ui_url}Fulfil the top-up action

   • Serve tabs like Sell / Transactions / Balance. The Sell tab is a Form (number, amount or product select); its submit posts an app_action to your server with the values plus the signed merchant context.
   • Fulfil against your provider, then respond with a success toast and refreshed balance — or a field-level error message the cashier can fix.
   • Money-movement UIs deserve confirmations: use the `confirm` key on destructive or irreversible actions.
3. 3

   Record the sale as a bill

   The service you sold becomes a real line on a real bill.

   • POST/apps-v1/sales/billsRecord the sale

   • After fulfilment, record the sale through the gateway so it lands in the merchant's reports, register session and day summary like any other sale.
   • Attribution comes free: the bill is created by your app's per-install user, so merchants can always see which sales came through you.
   • Keep fulfilment and billing transactional on your side: fulfil first, then bill; if billing fails, retry from a queue rather than dropping the record (a fulfilled top-up with no bill is a reconciliation hole).

   Read the docs for this step
4. 4

   Float, settlement & receipts

   Run the money lifecycle on your side; keep the merchant in the loop in-POS.

   • POST{your_webhook_url}Receive app.installed

   • A Balance tab (DetailCard + top-up Form) lets merchants see and refill their float without leaving Ewity — bank-transfer verification flows work well as a modal Form that submits a reference number.
   • Commission statements and settlement exports live on your side; link out with an open_url action.
   • Use `app.uninstalled` to freeze the account, not delete it — merchants reinstall.

   Read the docs for this step