Platform

What the spuke Developer Platform is and how to get an account.

Developer Platform overview

Build apps that merchants install on spuke.

What you can build

The spuke Developer Platform lets you ship software that merchants install into their spuke account. Apps read payment data, react to events in real time and can be sold in the spuke App Store.

Building block What it gives you
App Your listing, credentials and install lifecycle
App API REST access to a merchant's spuke resources, scoped by consent
Webhooks Signed, retried event delivery to your backend
Environments Isolated sandbox merchants for end-to-end testing
Monetization Free, one-time or subscription pricing in EUR

The lifecycle

  1. Create a developer account and complete verification.
  2. Create an app — it receives an 8-digit app number and a draft listing.
  3. Build against a sandbox environment with test merchants.
  4. Submit the app for review.
  5. Publish. Merchants install it from the spuke App Store.

Every app starts in test mode. Live credentials are only issued after review and payout verification.

Two modes, always separated

Test (sandbox) Live
Credentials test client id / secret live client id / secret
Data Sandbox merchants you own Real merchants who installed you
Money Simulated ledger Real payouts
Rate limits Counted separately Counted separately

A token minted in one mode can never read the other mode's data.

What an app is not

Apps are not a PSP integration. You never touch card data, never hold funds and never call the acquirer. spuke stays the merchant of the payment relationship; your app works on top of it.

Accounts & verification

Organizations, team members and payout KYC.

Developer accounts

Sign up at dev.spuke.com with email, Google or GitHub. Your account is separate from any merchant account — the same person can hold both, and sessions are isolated.

Organization

Every developer account belongs to one organization. The organization owns:

  • apps and their listings
  • API credentials and webhook endpoints
  • sandbox environments
  • the payout account and earnings

Team roles

Role Can do
Owner Everything, including payouts and deleting the organization
Admin Apps, credentials, environments, team invites
Developer Apps, credentials, sandbox — no payout access
Read-only View dashboards and logs

Invites are email-based and expire; revoked members lose API access immediately.

Verification

Verification unlocks live mode.

  1. Sandbox: verification is instant. No documents, no bank account, no real identity check.
  2. Live: you complete payout onboarding with our payout partner — legal entity, representative identity, and a bank account in a supported country.

While a payout account is restricted or disabled, publishing and payouts are paused automatically and you receive an in-app notification plus an email reminder until it is resolved.

Notifications

The bell in the developer dashboard carries anything that needs action: verification requirements, review results, webhook failures, rate-limit warnings and payout events. Critical items are mirrored to email.

Quickstart

From zero to a working install in about 15 minutes.

Follow this once end-to-end; every later chapter goes deeper on one step.

1. Create the app

Dashboard → Apps → New app. A draft is created immediately with an 8-digit app number, e.g. 41028837. Give it a name (min. 3 characters) and continue.

2. Grab test credentials

Step OAuth & webhooks of the wizard shows your test client id and secret and lets you set a redirect URI.

export SPUKE_CLIENT_ID=app_test_...
export SPUKE_CLIENT_SECRET=sk_app_test_...

3. Create a sandbox environment

Dashboard → Sandbox. An environment is an isolated fake merchant with its own products, payments and ledger. You get one by default and can create up to five.

4. Install your app into the environment

In the environment, choose Install app and pick your app. This runs the same OAuth consent flow a real merchant sees and produces a real access token — scoped to the sandbox merchant.

5. Call the App API

curl https://api.spuke.com/v1/app/v1/merchant \
  -H "Authorization: Bearer $ACCESS_TOKEN"

{
  "id": "mch_test_8f21",
  "business_name": "Sandbox Coffee GmbH",
  "country": "DE",
  "currency": "EUR",
  "mode": "test"
}

6. Receive an event

Add a webhook endpoint, subscribe to payment.succeeded, then trigger a payment from the environment's ledger tools. The delivery, the payload and every retry show up in Logs.

7. Submit

When the listing is complete and the checklist is green, submit for review. See Review & publishing.

Concepts & glossary

The words we use, and exactly what they mean.

Term Meaning
App Your product. Has one listing, one set of credentials per mode and many installations.
App number Stable 8-digit identifier of an app, used in URLs and support tickets.
Installation One merchant × one app × one mode. Holds the granted scopes and the tokens.
Scope A single permission such as payments:read. Granted by the merchant at install time.
Environment An isolated sandbox workspace containing a test merchant and its data.
Mode test or live. Determines credentials, data and quotas.
Event A change in the merchant's account we push to your webhook endpoint.
Listing The public App Store page: name, icon, screenshots, pricing, links.
Version A submitted snapshot of a listing plus the requested scopes. Reviewed as a unit.
Publishing fee One-time fee charged in live mode when a version is published.
Earnings Money owed to you from app sales, settled through payout cycles.

Identifier shapes

app number        41028837
installation      inst_… (public id) / UUID in API payloads
access token      spk_at_live_… / spk_at_test_…
refresh token     spk_rt_live_… / spk_rt_test_…
client id         spk_client_…
webhook secret    whsec_…
event id          evt_…

Identifiers are opaque strings. Never parse them; only compare them.