Quickstart

This guide takes you from zero to a working payment in a few requests. Use a sk_sandbox_… key so nothing touches real money.

Create a product

Define what you sell. Omit recurringInterval for a one-time product.

curl -X POST https://api.beta.suby.fi/v3/products \
  -H "Content-Type: application/json" \
  -H "X-Suby-Api-Key: sk_sandbox_your_key" \
  -d '{
    "name": "Pro Plan",
    "priceCents": "999",
    "currency": "EUR",
    "status": "ACTIVE"
  }'

The response data.id is your pro_… product id.

Create a customer (optional)

You can attach an existing customerId, or let the payment create one inline via customerData. To create one explicitly:

curl -X POST https://api.beta.suby.fi/v3/customers \
  -H "Content-Type: application/json" \
  -H "X-Suby-Api-Key: sk_sandbox_your_key" \
  -d '{ "email": "buyer@example.com", "firstName": "Ada" }'

Take a payment

The simplest integration is a hosted checkout session — mint a cs_… token and redirect the buyer to its url.

curl -X POST https://api.beta.suby.fi/v3/checkout/sessions \
  -H "Content-Type: application/json" \
  -H "X-Suby-Api-Key: sk_sandbox_your_key" \
  -d '{
    "mode": "payment",
    "productId": "pro_abc123",
    "successUrl": "https://your-app.com/success",
    "cancelUrl": "https://your-app.com/cancel"
  }'

Redirect the customer to data.url. For card test flows, use test card 4242 4242 4242 4242 with any future expiry and any CVC.

Get notified as the payment progresses.

curl -X POST https://api.beta.suby.fi/v3/webhook-endpoints \
  -H "Content-Type: application/json" \
  -H "X-Suby-Api-Key: sk_sandbox_your_key" \
  -d '{ "url": "https://your-app.com/webhooks/suby" }'

Store the returned data.secret (whsec_…) — it is shown once and is used to verify signatures.

Grant access

In your webhook handler, verify the signature and grant access on the right event (recommended strategy).

Direct (server-side) payment

If you collect the payment method yourself, call POST /v3/payments directly. Card flows return a checkout handle (redirect / 3DS); crypto flows return a deposit or wallet-connect instruction.

curl -X POST https://api.beta.suby.fi/v3/payments \
  -H "Content-Type: application/json" \
  -H "X-Suby-Api-Key: sk_sandbox_your_key" \
  -d '{
    "productId": "pro_abc123",
    "customerData": { "email": "buyer@example.com" },
    "method": "CARD",
    "card": { "tokenizedInstrument": "tok_test_visa" }
  }'

Full API reference

Every parameter and response field, endpoint by endpoint.

Get started

Core concepts

Direct (server-side) payment

Full API reference

​Direct (server-side) payment

Full API reference

Direct (server-side) payment