Reference app: Stripe

The fastest way to understand a payment app is to read one. The Stayblox app repo ships a complete, standalone Stripe provider at sample-apps/stripe-payments/. No framework, no Stayblox code, just the two endpoints and the GraphQL callback. Copy it as the starting point for any provider.

What it does

Method & path	Caller	Purpose
POST /sessions	Stayblox	Open a payment session; verify the signature, create a Stripe Checkout Session, return { redirect_url }.
POST /stripe-webhook	Stripe	On checkout.session.completed, call Stayblox's paymentSessionResolve to settle the session.
POST /refunds	Stayblox	Reverse a resolved session. Enabled because the manifest declares capabilities.refunds: true.

It maps directly onto the payment-session flow: Stayblox opens the session → buyer pays on Stripe → Stripe's webhook triggers the GraphQL resolve.

Configuration

The example reads these environment variables:

Variable	Where it comes from
STRIPE_SECRET_KEY	Stripe dashboard (the provider's own secret; never sent to Stayblox).
STRIPE_WEBHOOK_SECRET	Stripe webhook endpoint signing secret.
STAYBLOX_WEBHOOK_SECRET	Printed once when you run stayblox app install --team <slug>.
STAYBLOX_API_URL	https://api.stayblox.com/developer/api/2026-01/graphql (or pin a different version; see Versioning).
STAYBLOX_APP_TOKEN	Printed once when you run stayblox app install --team <slug>. Rotate with stayblox app token --team <slug>.

Run it locally

cd sample-apps/stripe-payments
STRIPE_SECRET_KEY=sk_test_... \
STAYBLOX_WEBHOOK_SECRET=... \
STAYBLOX_API_URL=https://app.stayblox.test/developer/api/2026-01/graphql \
STAYBLOX_APP_TOKEN=... \
php -S 0.0.0.0:8088 server.php

Then point the app's app.toml endpoints.payment_session at http://localhost:8088/sessions and add a Stripe webhook to http://localhost:8088/stripe-webhook.

Key things to copy

• Signature verification on /sessions before doing anything; see Signing & security.
• Amount conversion: Stayblox sends major units; Stripe wants the smallest unit (cents).
• Idempotent resolve: carry your Stayblox session_id through Stripe's client_reference_id / metadata so the webhook can resolve the right session, and rely on resolve being idempotent across webhook redelivery.

Multi-host

The reference handles a single host for clarity. In production, key host credentials by the install (X-Stayblox-App header / settings.stripe_account) so one server serves every host that installs your app.