POS webhook

A till or terminal can request IBR, show a QR, and be told when the chain has finalized the payment. This is the shop’s own service. It is not a payment company and it cannot declare finality.

How it works

Register the device with a webhook URL. You receive an apiKey and a webhookSecret once.
Open an invoice. The response includes a QR and a payment URI for the customer wallet.
The customer pays from IBRESE Wallet. The node records the transfer.
When the invoice is paid under the settlement policy, the POS service POSTs payment.finalized to your URL.

Run locally

POS_MERCHANT_ADDRESS=<64-hex-address> npm run pos

Listens on http://127.0.0.1:8101 and observes http://127.0.0.1:3001. consensusAuthority and finalityAuthority are always false.

API

POST /v1/pos/devices — register a till
POST /v1/pos/invoices — create invoice + QR · Authorization: Bearer <apiKey>
GET /v1/pos/invoices/:paymentId — status (not authoritative)
POST /v1/pos/webhooks/test — pos.ping
GET /v1/info — consensusAuthority: false

Register a device

curl -s -X POST http://127.0.0.1:8101/v1/pos/devices \
  -H 'content-type: application/json' \
  -d '{"name":"Till-1","webhookUrl":"https://shop.example/ibrese/webhook"}'

Create an invoice

curl -s -X POST http://127.0.0.1:8101/v1/pos/invoices \
  -H 'authorization: Bearer <apiKey>' \
  -H 'content-type: application/json' \
  -d '{"amount":"40","merchantReference":"ORDER-123"}'

amount is native IBR subunits as a decimal string. merchantReference is shop metadata, not a consensus field.

Webhook

JSON POST. Verify HMAC-SHA256(webhookSecret, "<t>.<raw-body>"). Reject if the timestamp is skewed. Treat the event as an observation until you confirm GET /payments/:id on your own node.

X-IBRESE-Webhook-Signature: t=<unix-ms>,v1=<hmac-sha256-hex>
X-IBRESE-Webhook-Event: payment.finalized
X-IBRESE-Webhook-Id: <event-id>

pos.ping · payment.updated · payment.finalized · payment.expired

Mark the sale paid only on payment.finalized with invoicePaid true. UNDERPAYMENT is not paid. OVERPAYMENT is paid and the excess is visible. The payload sets authoritative: false.

Full POS and shop guide

How a till or an online shop connects: run your own merchant-pos, register a device, open an invoice, verify the HMAC webhook, confirm FINALIZED on a node. Example files and OpenAPI are on this site.

https://ibrese.com/docs/pos/

Files

Download OpenAPI, discovery JSON, curl, webhook receivers (Node, Python, PHP) and a WooCommerce skeleton.