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.

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	App settings → Connection details → Webhook secret.
STAYBLOX_API_URL	App settings → Connection details → GraphQL endpoint.
STAYBLOX_APP_TOKEN	App settings → Generate API token.

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 marketplace app's manifest 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.