Skip to content
Reference, STRYK POS

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.

Last updated: Developers
Contents
  1. Overview
  2. Keys and security
  3. Room account and amounts
  4. Posting and retrying
  5. Cancellation and invoice
  6. Webhooks and acceptance
  7. Technical reference

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.

ItemValue
Base addresshttps://app.staystryk.com/api/v1/pos/public
LoginHotel's bearer key in the Authorization header
RequirementThe hotel has the STRYK POS add-on module active
Without the add-on moduleEvery call returns 403 with the code module_disabled. STRYK does not post any charge.
Rate limit100 requests per 60 seconds and key. After that STRYK responds with 429.
Version of this description1.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 pathPurpose
GET /pingOnly checks whether the key is accepted.
GET /accountsLists the currently checked-in room accounts, including blocked ones.
GET /room-lookup?room=105Resolves a room to the checked-in stay. 404 without a matching guest, 409 for an ambiguous room.

The room account contains these fields:

FieldMeaning
bookingId, bookingNumber, guestName, roomNumberStay and room
allowPostingThe hotel has allowed charges for the stay. This alone is not enough.
allowChargeOverall check from permission, remaining credit and closed account. Check it immediately before posting.
postingBlockReasonno_post, credit_limit_reached, account_closed or empty
openChargesCount, openChargesTotal, stayChargesTotalOpen charges and total of the non-cancelled charges
creditLimit, remainingCredit, currencyLimit, 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 pathPurpose
POST /chargesPosts one charge to a room account. Response 201 with the charge.
POST /charges/batchPosts 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:

FieldRequiredMeaning
bookingId, roomat least oneRoom as text with letters, not as a number. If both are given, they must match.
descriptionyes1 to 500 characters
unitPriceyesGross price per unit, greater than 0, at most 99999.99
externalRefyesUnique receipt or charge key, 1 to 255 characters, for example receipt-123-item-1
quantityno0.001 to 9999, default 1
unitnoat most 20 characters, default Stk.
taxRatenoActive tax rate of the hotel. If omitted, the outlet's default applies, then the central one.
currencynoMust be the hotel currency
outletIdnoFor a key with an outlet, this outlet applies. Any other value returns 403.
chargedAtnoTime of service, default now, at most 5 minutes in the future
notes, posRefnoNote (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.

StatusMeaning
400Invalid details, correct them.
401Key cannot be verified
403Scope not allowed, for example wrong outlet
404Account or charge not found
409Business conflict. Check the code, do not retry blindly.
429Rate limit, wait at least 60 seconds
5xxReconcile 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, cancelled or transferred.
  • A charge stays open until check-out creates the invoice. Then STRYK takes open charges into invoice items and the status changes to transferred.
  • 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.

ItemValue
Eventscharge.posted, charge.cancelled, ping when testing
Header X-STRYK-EventEvent name
Header X-STRYK-Webhook-IdID of the webhook, not of the delivery
Header X-STRYK-Signaturesha256= and HMAC-SHA-256 of the unchanged request bytes. Only with a configured secret.
Bodyevent, hotelId, timestamp, data with chargeId, externalRef, bookingId, roomNumber, guestName, description, grossAmount, currency and outlet
Response2xx after permanent acceptance within 10 seconds. STRYK does not follow redirects.
RetryAfter 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:

  1. Check /ping and guest and room assignment, also for bookings with several rooms.
  2. Check tax, currency and the outlet restriction of the key.
  3. Exact repetition without duplicate charges, changed content with 409, lost response with reconciliation.
  4. Batch all or nothing, lock and limit, cancellation and cancellation repetition.
  5. Invoice totals at check-out and rejection of the cancellation after transfer.
  6. Signed webhook, invalid signature, duplicate and swapped delivery.
  7. 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.

MethodPathShort description
GET/pingCheck connection
GET/accountsList checked-in room accounts
GET/room-lookupFind the stay for a room
POST/chargesPost a charge
POST/charges/batchPost up to 50 charges together
GET/charges/{externalRef}Read the state of a charge
DELETE/charges/{externalRef}Cancel an open charge
Questions about STRYK?