POS cihazı ve mağaza sistemi nasıl bağlanır

IBRESE merkezi bir ödeme şirketi değildir. Kasa veya e-ticaret, kendi merchant-pos servisinizi çalıştırır; müşteri IBRESE Cüzdan ile öder; durum kendi düğümünüzün (veya güvendiğiniz public node’un) GET /payments/:id yanıtından türetilir. Bu sayfa ve yanındaki dosyalar bağlanmak için yeterlidir.

ibrese.com /v1/pos barındırmaz. Cihaz kaydı ve fatura, sizin makinenizdeki servise gider (http://127.0.0.1:8101 veya iç ağ). Public RPC yalnız gözlemdir: https://rpc.ibrese.com. consensusAuthority ve finalityAuthority her zaman false.

Kim ne bağlar

Senaryo	Ne yapılır
Fiziksel kasa / Android-Windows POS yazılımı	Mağazada `merchant-pos` çalışır. Cihaz `POST /v1/pos/devices` ile kaydolur, her satışta fatura açar, QR gösterir. İsterseniz hazır kasa teması: `GET /`.
E-ticaret, ERP, WooCommerce, özel checkout	Shop backend bir “cihaz” gibi kaydolur. Webhook URL sipariş sisteminize aittir. Ödeme sayfasında fatura + QR. `payment.finalized` gelince siparişi kendi node doğrulamanızdan sonra ödendi işaretlersiniz.
Doğrudan Payment Protocol (POS servisi yok)	Kendi kodunuz canonical PaymentRequest + `cryptoproject://pay` üretir. Durumu `GET https://rpc.ibrese.com/payments/{paymentId}` ile okursunuz. Webhook zorunlu değildir.

Mimari

POS cihazı veya shop checkout
        │  POST /v1/pos/invoices   (sizin merchant-pos)
        ▼
canonical PaymentRequest + QR + URI
        │  müşteri IBRESE Wallet tarar / açar
        ▼
imzalı transfer  →  ibrese-l1  (data = PAYMENT_BIND)
        │
        ▼
sizin merchant-pos  GET {node}/payments/:id  (gözlem)
        │  HMAC POST
        ▼
sizin webhook URL  (kasa “ödendi” / sipariş paid)
        │  yeniden doğrulayın
        ▼
GET https://rpc.ibrese.com/payments/:id  veya kendi node’unuz

Ağ: networkId=ibrese, chainId=ibrese-l1, varlık NATIVE (IBR). URI şeması: cryptoproject://pay?…

Tutar

Zincir 5 ondalık kullanır. 1 IBR = 100000 alt birim. API amount alanı ondalık string alt birimdir, fiat değildir.

Vitrin	Kuruş (2 ondalık)	API amount
0,01 IBR	1	`"1000"`
1,00 IBR	100	`"100000"`
12,50 IBR	1250	`"1250000"`

merchantReference sipariş numarasıdır; consensus alanı değildir. Her fatura için benzersiz tutun.

1. merchant-pos’u çalıştırın

POS_MERCHANT_ADDRESS=<64-hex-alıcı-adres> \
POS_NODE_URL=https://rpc.ibrese.com \
POS_NETWORK_ID=ibrese \
POS_CHAIN_ID=ibrese-l1 \
POS_HOST=127.0.0.1 \
POS_PORT=8101 \
npm run pos

POS_MERCHANT_ADDRESS IBR’nin yatacağı hesap. Cihaz kaydında recipient ile kasa bazında değiştirebilirsiniz. Üretim webhook’ları için POS_REQUIRE_HTTPS=1. Kasa arayüzü: http://127.0.0.1:8101/

2. POS cihazını bağlayın

Cihazın ulaşabileceği bir webhook URL’si hazırlayın (aşağıdaki örnek dosyalar).
POST /v1/pos/devices — yanıtta apiKey ve webhookSecret bir kez gelir. Kasada ve sunucuda saklayın.
POST /v1/pos/webhooks/test ile pos.ping doğrulayın.
Satışta POST /v1/pos/invoices + Bearer apiKey. Yanıttaki qrPng (data URL) veya uri müşteriye gösterilir.
Cihaz GET /v1/pos/invoices/:paymentId poll eder veya webhook bekler. Satışı yalnız invoicePaid: true iken kapatın.

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

Hazır kasa ekranı için tarayıcıyı http://127.0.0.1:8101/ açın — tuş takımı, QR, ödendi. Üçüncü parti POS yazılımı aynı REST’i çağırır; IBRESE’ye doğrudan bağlanmaz.

3. Shop sistemini bağlayın

Checkout backend’i bir cihaz olarak kaydedin; webhook = sipariş endpoint’iniz.
Müşteri ödeye tıklayınca fatura açın; merchantReference=ORDER-{id}.
Sayfada QR (qrPng) ve “cüzdanla aç” (uri) gösterin.
Webhook payment.finalized + invoicePaid true → X-IBRESE-Webhook-Id ile idempotent olun → GET https://rpc.ibrese.com/payments/{paymentId} (veya kendi node) FINALIZED ve MATCH/OVERPAYMENT ise siparişi paid yapın.

WooCommerce iskeleti: woocommerce-ibrese.php.example. Checkout script: shop-checkout.mjs.

HTTP API

Açık API: openapi.json · keşif: discovery.json

Yöntem	Yol	Auth	Açıklama
GET	`/`	—	Kasa HTML
GET	`/v1/info`	—	`role: merchant-pos`
POST	`/v1/pos/devices`	—	Cihaz; apiKey + webhookSecret bir kez
POST	`/v1/pos/invoices`	Bearer	Fatura, uri, qr, qrPng
GET	`/v1/pos/invoices/:paymentId`	Bearer	Durum; node yenilenir; otorite değil
GET	`/v1/pos/invoices`	Bearer	Bu cihazın faturaları
POST	`/v1/pos/webhooks/test`	Bearer	`pos.ping`
POST	`/v1/pos/poll`	Bearer	Toplu yenileme
GET	`https://rpc.ibrese.com/payments/:id`	—	Public node gözlemi

Fatura yanıtı (özet): paymentId, amount, recipient, uri, qr, qrPng, paid, lastVerification, authoritative: false.

Webhook

JSON POST. Ham gövdeyi byte-byte kullanın (JSON’u yeniden stringify etmeyin).

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

HMAC-SHA256(webhookSecret, "<t>.<raw-body>"). |now − t| > 5 dakika ise reddedin. 2xx dönün. 4xx (429 hariç) yeniden denenmez; 5xx / ağ 5 denemeye kadar (50ms · 2^(n−1)) tekrarlanır.

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

Gövde her zaman authoritative: false, source: "merchant-pos-observer" taşır. Satışı payment.finalized ve invoicePaid: true olmadan kapatmayın.

Settlement politikası

Gözlem	invoicePaid	policy
Mempool / blok QC’siz	false	UNFINALIZED
FINALIZED, tutar eksik	false	UNDERPAYMENT
FINALIZED, tutar eşit	true	PAID
FINALIZED, fazla	true	OVERPAYMENT
Aynı paymentId’ye birden fazla finalized tx	true	MULTIPLE

Durum kodları: REQUESTED, PENDING, INCLUDED, FINALIZED, FAILED, EXPIRED, UNKNOWN.

Güvenlik

Webhook’a körü körüne güvenmeyin; node GET /payments/:id ile doğrulayın.
apiKey / webhookSecret’i URL’ye, QR’a, log’a yazmayın.
webhookUrl kullanıcı/şifre içeremez. Üretimde HTTPS.
POS finality ilan etmez. Gateway otorite değildir.
Bu sitede kurtarma kelimesi / özel anahtar girmeyin.

Dosyalar

Hepsi statik; PHP örnekleri .example uzantılıdır (sunucuda çalışmaz). Toplu indirme: ibrese-pos-connect.zip

discovery.jsonmakine okur keşif
openapi.jsonHTTP şema
examples/curl.shkayıt + fatura
examples/hmac-verify.mjsHMAC
examples/webhook-node.mjsNode alıcı
examples/webhook-python.pyPython alıcı
examples/webhook-php.examplePHP alıcı
examples/shop-checkout.mjse-ticaret checkout
examples/pos-device.mjskasa yazılımı
examples/woocommerce-ibrese.php.example WooCommerce iskeleti
MERCHANT_PROTOCOL.mdmerchant yüzeyi
PAYMENT_PROTOCOL.mdödeme protokolü

Özet sayfa: /pos.html · soru: info@ibrese.com

How to connect a POS device or a shop system

IBRESE is not a payment company. A till or an online shop runs its own merchant-pos service. The customer pays from IBRESE Wallet. Status is derived from GET /payments/:id on a node you trust. This page and the files beside it are enough to integrate.

ibrese.com does not host /v1/pos. Device registration and invoices go to your process (http://127.0.0.1:8101 or your LAN). Public RPC is observation only: https://rpc.ibrese.com. consensusAuthority and finalityAuthority are always false.

Who connects what

Scenario	What you do
Physical till / POS app	Run `merchant-pos` in the shop. The device registers with `POST /v1/pos/devices`, opens an invoice per sale, shows the QR. Built-in till UI: `GET /`.
Ecommerce, ERP, WooCommerce, custom checkout	The shop backend registers as a device. The webhook URL is your order endpoint. Checkout creates an invoice + QR. On `payment.finalized` mark the order paid after you confirm it on a node.
Payment Protocol only (no POS service)	Your code builds a canonical PaymentRequest and a `cryptoproject://pay` URI. Poll `GET https://rpc.ibrese.com/payments/{paymentId}`. No webhook required.

Architecture

POS device or shop checkout
        │  POST /v1/pos/invoices   (your merchant-pos)
        ▼
canonical PaymentRequest + QR + URI
        │  customer scans with IBRESE Wallet
        ▼
signed transfer  →  ibrese-l1  (data = PAYMENT_BIND)
        │
        ▼
your merchant-pos  GET {node}/payments/:id  (observer)
        │  HMAC POST
        ▼
your webhook URL  (till “paid” / order paid)
        │  re-verify
        ▼
GET https://rpc.ibrese.com/payments/:id  or your own node

Network: networkId=ibrese, chainId=ibrese-l1, asset NATIVE (IBR). URI scheme: cryptoproject://pay?…

Amount

The chain uses 5 decimals. 1 IBR = 100000 subunits. API amount is a decimal string of native subunits, not fiat.

Display	Cents (2 dp)	API amount
0.01 IBR	1	`"1000"`
1.00 IBR	100	`"100000"`
12.50 IBR	1250	`"1250000"`

merchantReference is the order id. It is not a consensus field. Keep it unique per invoice.

1. Run merchant-pos

POS_MERCHANT_ADDRESS=<64-hex-receive-address> \
POS_NODE_URL=https://rpc.ibrese.com \
POS_NETWORK_ID=ibrese \
POS_CHAIN_ID=ibrese-l1 \
POS_HOST=127.0.0.1 \
POS_PORT=8101 \
npm run pos

POS_MERCHANT_ADDRESS is where IBR lands. Override per till with recipient on device registration. Production webhooks: POS_REQUIRE_HTTPS=1. Till UI: http://127.0.0.1:8101/

2. Connect a POS device

Prepare a webhook URL the till can reach (see example files).
POST /v1/pos/devices — apiKey and webhookSecret are returned once. Store them on the till and the shop server.
Call POST /v1/pos/webhooks/test for pos.ping.
On each sale POST /v1/pos/invoices with Bearer apiKey. Show qrPng (data URL) or uri to the customer.
Poll GET /v1/pos/invoices/:paymentId or wait for the webhook. Close the sale only when invoicePaid is true.

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"}'

Built-in till: open http://127.0.0.1:8101/ — keypad, QR, paid. Third-party POS software calls the same REST API; it does not talk to ibrese.com directly.

3. Connect a shop system

Register the checkout backend as a device; webhook = your order endpoint.
On pay, create an invoice; merchantReference=ORDER-{id}.
Show QR (qrPng) and “open in wallet” (uri).
On webhook payment.finalized + invoicePaid true → dedupe X-IBRESE-Webhook-Id → GET https://rpc.ibrese.com/payments/{paymentId} (or your node). If FINALIZED and MATCH/OVERPAYMENT, mark the order paid.

WooCommerce skeleton: woocommerce-ibrese.php.example. Checkout script: shop-checkout.mjs.

HTTP API

OpenAPI: openapi.json · discovery: discovery.json

Method	Path	Auth	Meaning
GET	`/`	—	Till HTML
GET	`/v1/info`	—	`role: merchant-pos`
POST	`/v1/pos/devices`	—	Device; apiKey + webhookSecret once
POST	`/v1/pos/invoices`	Bearer	Invoice, uri, qr, qrPng
GET	`/v1/pos/invoices/:paymentId`	Bearer	Status; refreshes from node; not authoritative
GET	`/v1/pos/invoices`	Bearer	Invoices for this device
POST	`/v1/pos/webhooks/test`	Bearer	`pos.ping`
POST	`/v1/pos/poll`	Bearer	Refresh all open invoices
GET	`https://rpc.ibrese.com/payments/:id`	—	Public node observation

Invoice payload (summary): paymentId, amount, recipient, uri, qr, qrPng, paid, lastVerification, authoritative: false.

Webhook

JSON POST. Verify the raw body byte-for-byte (do not re-stringify JSON).

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

HMAC-SHA256(webhookSecret, "<t>.<raw-body>"). Reject if |now − t| > 5 minutes. Return 2xx. 4xx (except 429) is not retried; 5xx / network up to 5 attempts (50ms · 2^(n−1)).

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

Every payload sets authoritative: false and source: "merchant-pos-observer". Do not close a sale without payment.finalized and invoicePaid: true.

Settlement policy

Observation	invoicePaid	policy
Mempool / block without QC	false	UNFINALIZED
FINALIZED, amount short	false	UNDERPAYMENT
FINALIZED, exact amount	true	PAID
FINALIZED, excess	true	OVERPAYMENT
Several finalized txs for one paymentId	true	MULTIPLE

Statuses: REQUESTED, PENDING, INCLUDED, FINALIZED, FAILED, EXPIRED, UNKNOWN.

Security

Do not trust the webhook alone; confirm GET /payments/:id on a node.
Never put apiKey / webhookSecret in a URL, QR, or log.
webhookUrl must not contain credentials. Use HTTPS in production.
POS does not declare finality. A gateway is not authority.
Never type a recovery phrase or private key on this site.

Files

All static. PHP samples use .example so the web server will not execute them. Bundle: ibrese-pos-connect.zip

discovery.jsonmachine-readable discovery
openapi.jsonHTTP schema
examples/curl.shregister + invoice
examples/hmac-verify.mjsHMAC
examples/webhook-node.mjsNode receiver
examples/webhook-python.pyPython receiver
examples/webhook-php.examplePHP receiver
examples/shop-checkout.mjsshop checkout
examples/pos-device.mjstill software
examples/woocommerce-ibrese.php.example WooCommerce skeleton
MERCHANT_PROTOCOL.mdmerchant surface
PAYMENT_PROTOCOL.mdpayment protocol

Short page: /pos.html · questions: info@ibrese.com