Build apps

Apps are integrations that run on your server and talk to Stayblox over the Developer GraphQL API. Today that means payment providers; channel managers are next (the protocol shapes already exist — see Channel managers).

Building a storefront theme instead? That's a different surface → Build themes.

Mental model

An app has two halves of one conversation:

• Platform → app — Stayblox makes signed HTTP calls to endpoints you declare in your app's manifest (e.g. "open a payment session", "refund").
• App → platform — your server calls the Developer GraphQL API with a per-install bearer token to report outcomes (e.g. "this session is paid").

Secrets stay on your server. Stayblox only ever sends the install identifier plus the non-secret config the host entered, so one server can serve every host that installs your app.

The payment-session flow

 Buyer picks your app at checkout
         │
 Stayblox ──POST {payment_session} (HMAC signed)──▶  your app
         │                                            opens a hosted payment page
 Stayblox ◀──────── { redirect_url } ────────────────┘
         │
   redirect buyer ──▶ your hosted page ──▶ buyer pays
                                             │
 your app ◀──── provider callback / webhook ─┘
         │
 your app ──GraphQL paymentSessionResolve (Bearer token)──▶  Stayblox
         │
 Stayblox marks the booking paid; buyer returns to return_url

The session moves through a fixed set of states on the Stayblox side; your mutations drive the transitions. See Payment apps for the full lifecycle and copy-paste examples.

Where to go next

• Getting started — token, webhook secret, endpoint, first call.
• Versioning — dated API versions, how to pin one.
• GraphQL reference — the full schema, generated from the SDL.
• Payment apps — manifest, settings, session payload, mutations.
• Signing & security — verify our requests, sign yours.
• Reference app — a complete working Stripe example.