Restaurant POS

The POS keeps taking every other payment as usual: cash, card, transfer. Only one thing changes. When the waiter closes a tab “to the room”, the POS sends us the charge, it lands on the guest’s stay folio, and it is settled at check-out.

It works for Soft Restaurant, Parrot, Loyverse or any other point of sale that can make a signed HTTP call when closing a tab.

• There are three calls: find the guest in a room, post the charge, and void it if the waiter got it wrong.
• Amounts travel in cents and in the booking’s currency.
• The ticket number is the idempotency key. Retrying with the same ticket number does not charge twice.

The hotel creates the connection in its panel, under Settings → Restaurant POS, and receives the credential pair once and only once.

Each connection belongs to one property: it only sees and charges stays in that property. The hotel can cap the maximum amount per charge, switch charging off, rotate the secret — the previous one stops working immediately — or revoke the connection outright.

https://api.yareserva.com/api/v1/webhooks/pos

X-YR-POS-Key:       <keyId>
X-YR-POS-Timestamp: <segundos Unix, UTC>
X-YR-POS-Signature: sha256=<hex(HMAC-SHA256(secret, timestamp + "." + cuerpo))>

• The body is the exact bytes you send. Sign after serializing the JSON and do not reformat it.
• On GET requests the body is empty: you sign “timestamp + "."”, so the string ends at the dot.
• The POS clock can differ from ours by at most five minutes. Outside that window the request is rejected; sync the clock with NTP.
• Any failure — unknown or revoked key, wrong signature, time out of range — answers 401 INVALID_SIGNATURE and nothing is processed.
• The body cannot exceed 64 KB, and there is a cap of 300 requests per minute per IP.

KEY=yrpos_3f9a1c0b7d2e4a6f8b0c1d2e
SECRET=yrpos_sk_...
BODY='{"externalId":"TK-000123","roomNumber":"204","amountCents":45000,"description":"Cena mesa 7"}'
TS=$(date +%s)
SIG=$(printf '%s.%s' "$TS" "$BODY" | openssl dgst -sha256 -hmac "$SECRET" -hex | sed 's/^.* //')

curl -X POST https://api.yareserva.com/api/v1/webhooks/pos/charges \
  -H "Content-Type: application/json" \
  -H "X-YR-POS-Key: $KEY" \
  -H "X-YR-POS-Timestamp: $TS" \
  -H "X-YR-POS-Signature: sha256=$SIG" \
  --data-binary "$BODY"

const crypto = require('crypto');

const body = JSON.stringify(payload);
const ts = Math.floor(Date.now() / 1000).toString();
const sig = crypto.createHmac('sha256', secret).update(`${ts}.${body}`).digest('hex');

// headers: X-YR-POS-Key, X-YR-POS-Timestamp: ts, X-YR-POS-Signature: `sha256=${sig}`

import hashlib, hmac, json, time

body = json.dumps(payload, separators=(",", ":")).encode()
ts = str(int(time.time()))
sig = hmac.new(secret.encode(), ts.encode() + b"." + body, hashlib.sha256).hexdigest()

• Retry with the same externalId on any network error, timeout or 5xx. If the charge had already landed, you get 200 with “duplicate”: true and the same chargeId: it is not charged twice.
• The charge record and the folio movement are written in the same transaction. Two simultaneous retries cannot duplicate the charge.
• Generate a fresh timestamp and signature on every retry: the old signature expires after five minutes.
• Do not retry a 4xx without fixing the request. The exception is 429, which you retry respecting Retry-After.
• Voiding is safe to repeat: the second time it answers 409 CHARGE_ALREADY_VOIDED, which for you means the same as success.