G
YouTube TikTok Games
Skip to main content
New to the API? Start with the Quickstart: it takes you from a test key to a verified payment.

Which payment endpoint should I use?

Initialize Payment (redirect)

Recommended for most integrations. No PCI-DSS certification required. Spotflow hosts the checkout page and the customer is redirected to complete payment.

API conventions

Base URL

There’s one base URL for test and live mode. Your API key decides which environment a request runs in. See Test mode vs live mode.

Authentication

Every request authenticates with your secret key in the Authorization header:
Use sk_test_ keys in test mode and sk_live_ keys in live mode. Your public key (pk_…) is only for client-side integrations such as Spotflow Inline and the mobile SDKs. Find your keys in Settings → API Keys on the dashboard. See Authentication.

Requests and responses

  • HTTPS only. Requests over plain HTTP fail.
  • JSON in, JSON out. Send request bodies as JSON with Content-Type: application/json. Responses are JSON.
  • RESTful. Resource-oriented URLs such as /payments and /plans, standard HTTP methods (GET, POST, PUT, DELETE) and standard status codes. Any exceptions are documented on the endpoint.
  • Amounts are in the major unit of the currency. 5.00 with GHS means five Ghana cedis, not five pesewas.
  • References are yours. Send a unique reference when you create a payment or a disbursement. It identifies the transaction and is its idempotency key.

Versioning

The current API version is v1, and it’s part of every path (/api/v1). See the Changelog for what has changed.

Errors and limits

  • Calls without valid authentication return 401 Unauthorized. See Error codes.
  • Requests are rate-limited per key: 60 per minute in test mode and 300 per minute in live mode. A 429 response tells you how long to wait in Retry-After. See Rate limits.

Every endpoint page

Each endpoint in this reference lists its parameters, request body and documented status codes with example responses. Use the Try it playground on any endpoint page to send a request with your test secret key and inspect the response in your browser.

More conventions

Idempotency

Retry safely without creating duplicates.

Pagination

Walk through long lists with page and size.

Payment lifecycle

Every state a payment and subscription can be in.

Rate limits

Limits per key, and what to do on a 429.

Webhooks

Real-time notifications for your server.

Error codes

What each error means and how to fix it.