POS Posting API for POS vendors
The STRYK POS Posting API posts charges from your POS to room accounts of checked-in guests. The reference covers login, posting, cancellation and webhooks.
Contents
Overview
The API is a server-to-server interface for charges on checked-in stays. The hotel connects your POS in Settings under POS: Connect POS. There the POS receives a key and the Address for the POS.
| Item | Value |
|---|---|
| Base address | https://app.staystryk.com/api/v1/pos/public |
| Login | Hotel's bearer key in the Authorization header |
| Requirement | The hotel has the STRYK POS add-on module active |
| Without the add-on module | Every call returns 403 with the code module_disabled. STRYK does not post any charge. |
| Rate limit | 100 requests per 60 seconds and key. After that STRYK responds with 429. |
| Version of this description | 1.3.0 |
Keys and security
- The key starts with
pos_live_. The hotel sees it only once, when it is created. - Send it only server-side over HTTPS in the header:
Authorization: Bearer <vollständiger Schlüssel>. Never as a parameter in the URL. - A key belongs to exactly one hotel and optionally to one outlet. The hotel creates one key per connection.
- 401 means STRYK could not verify the key. Check the configuration and operating status. Do not switch the key automatically.
- A new key is a new idempotency scope. It does not find or cancel charges of the old key. Work through open jobs and reconcile them before the hotel revokes the old key.
- If a key is lost or compromised, the hotel revokes it with Revoke key and clarifies unsafe operations in STRYK before your POS sends a replacement.
Room account and amounts
| Method and path | Purpose |
|---|---|
GET /ping | Only checks whether the key is accepted. |
GET /accounts | Lists the currently checked-in room accounts, including blocked ones. |
GET /room-lookup?room=105 | Resolves a room to the checked-in stay. 404 without a matching guest, 409 for an ambiguous room. |
The room account contains these fields:
| Field | Meaning |
|---|---|
bookingId, bookingNumber, guestName, roomNumber | Stay and room |
allowPosting | The hotel has allowed charges for the stay. This alone is not enough. |
allowCharge | Overall check from permission, remaining credit and closed account. Check it immediately before posting. |
postingBlockReason | no_post, credit_limit_reached, account_closed or empty |
openChargesCount, openChargesTotal, stayChargesTotal | Open charges and total of the non-cancelled charges |
creditLimit, remainingCredit, currency | Limit, remaining credit and hotel currency |
Show the guest and room for confirmation and send bookingId together with room. Do not keep the account list permanently as a guest directory. Amounts are JSON numbers in the hotel currency. Rounding is HALF_UP: quantity to three, amounts to two decimal places.
Posting and retrying
| Method and path | Purpose |
|---|---|
POST /charges | Posts one charge to a room account. Response 201 with the charge. |
POST /charges/batch | Posts 1 to 50 charges together. Either all new charges are posted or none. The response follows the order of the request. |
GET /charges/{externalRef} | Returns the persistent state of a charge, including cancelled and transferred. |
Fields of a charge:
| Field | Required | Meaning |
|---|---|---|
bookingId, room | at least one | Room as text with letters, not as a number. If both are given, they must match. |
description | yes | 1 to 500 characters |
unitPrice | yes | Gross price per unit, greater than 0, at most 99999.99 |
externalRef | yes | Unique receipt or charge key, 1 to 255 characters, for example receipt-123-item-1 |
quantity | no | 0.001 to 9999, default 1 |
unit | no | at most 20 characters, default Stk. |
taxRate | no | Active tax rate of the hotel. If omitted, the outlet's default applies, then the central one. |
currency | no | Must be the hotel currency |
outletId | no | For a key with an outlet, this outlet applies. Any other value returns 403. |
chargedAt | no | Time of service, default now, at most 5 minutes in the future |
notes, posRef | no | Note (1000 characters), receipt reference for reception (100 characters) |
The total from quantity and unit price is greater than 0 and at most 99999999.99.
externalRef is the immutable idempotency key of the hotel and key. An exact repetition returns the original charge with idempotentReplay=true. Changed content or a cancelled key returns 409.
After a timeout or 5xx, first read GET /charges/{externalRef}. Only after a confirmed 404 send the same request unchanged with the same key. Store requests before sending and never change chargedAt, price, tax or reference. If the response shows duplicateWarning, the charge has already been posted. Reconcile it in STRYK and do not send it again.
| Status | Meaning |
|---|---|
| 400 | Invalid details, correct them. |
| 401 | Key cannot be verified |
| 403 | Scope not allowed, for example wrong outlet |
| 404 | Account or charge not found |
| 409 | Business conflict. Check the code, do not retry blindly. |
| 429 | Rate limit, wait at least 60 seconds |
| 5xx | Reconcile first, then retry with limited backoff |
Error response codes include pos_currency_mismatch, pos_external_ref_conflict, pos_external_ref_cancelled, pos_room_required, pos_guest_not_inhouse, pos_posting_blocked, pos_credit_limit_exceeded, pos_charge_already_invoiced and pos_account_closed. Do not branch on the German text. requestId helps support.
Cancellation and invoice
DELETE /charges/{externalRef} cancels an open charge of your key. The body optionally contains reason (at most 500 characters). A repetition returns the cancelled charge again.
- The status of a charge is
open,cancelledortransferred. - A charge stays
openuntil check-out creates the invoice. Then STRYK takes open charges into invoice items and the status changes totransferred. - A transferred charge returns 409 with
pos_charge_already_invoiced. The hotel corrects it in accounting: Correct an invoice. - A cancellation deletes nothing and refunds nothing. The cancelled charge remains traceable.
The API posts positive charges. Payments completed at the POS are not additionally sent to the room. For split payments, send only the open room share with correctly distributed tax. Deduct discounts from the gross price before posting.
Webhooks and acceptance
The hotel sets up webhooks in Settings under POS: Create webhooks.
| Item | Value |
|---|---|
| Events | charge.posted, charge.cancelled, ping when testing |
Header X-STRYK-Event | Event name |
Header X-STRYK-Webhook-Id | ID of the webhook, not of the delivery |
Header X-STRYK-Signature | sha256= and HMAC-SHA-256 of the unchanged request bytes. Only with a configured secret. |
| Body | event, hotelId, timestamp, data with chargeId, externalRef, bookingId, roomNumber, guestName, description, grossAmount, currency and outlet |
| Response | 2xx after permanent acceptance within 10 seconds. STRYK does not follow redirects. |
| Retry | After 30 seconds, 5 minutes, 30 minutes and 2 hours, up to the stored limit |
Verify the signature over the unchanged body before reading it as JSON. Store event and data.chargeId permanently to detect retries. Deliveries may arrive twice or out of order: an old charge.posted does not overwrite a charge.cancelled. There are no webhooks for check-in, check-out and invoice transfer. Read the state there again.
Acceptance checklist with a test hotel and a real checked-in test stay:
- Check
/pingand guest and room assignment, also for bookings with several rooms. - Check tax, currency and the outlet restriction of the key.
- Exact repetition without duplicate charges, changed content with 409, lost response with reconciliation.
- Batch all or nothing, lock and limit, cancellation and cancellation repetition.
- Invoice totals at check-out and rejection of the cancellation after transfer.
- Signed webhook, invalid signature, duplicate and swapped delivery.
- Error display, key change and reconciliation by staff.
Technical reference
The full description is available as an OpenAPI file in English, as YAML at /developers/pos/openapi.yaml and as JSON at /developers/pos/openapi.json on the STRYK website. In the hotel, Technical documentation in the section For the POS technician under Settings and POS leads to this page.
| Method | Path | Short description |
|---|---|---|
| GET | /ping | Check connection |
| GET | /accounts | List checked-in room accounts |
| GET | /room-lookup | Find the stay for a room |
| POST | /charges | Post a charge |
| POST | /charges/batch | Post up to 50 charges together |
| GET | /charges/{externalRef} | Read the state of a charge |
| DELETE | /charges/{externalRef} | Cancel an open charge |