Quickstart

Zero to a working payment in four requests. Use a sk_sandbox_… key · nothing touches real money.

Create a product

Omit recurringInterval for a one-time product; set it for a subscription plan.

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" }'

data.id is your pro_….

Open a 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"
  }'

Test card 4242 4242 4242 4242, any future expiry, any CVC.

Add your destination in dashboard settings and store the whsec_… secret it shows once · you need it to verify signatures.

Grant access

In your handler, verify the signature and grant on the right event · which one depends on the payment method.

Charge without a hosted page

Two calls, in this order, and only for the pay-as-you-go case · metered billing, a top-up, a threshold crossed. 1. Store the card. A setup session takes no amount and charges nothing.

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": "setup",
    "customer": { "email": "buyer@example.com" },
    "successUrl": "https://your-app.com/saved",
    "cancelUrl": "https://your-app.com/cancel"
  }'

Send the buyer to data.url. Once they are through, read the stored card:

curl https://api.beta.suby.fi/v3/customers/cus_abc123/payment-methods \
  -H "X-Suby-Api-Key: sk_sandbox_your_key"

2. Debit it later, with nobody in front of the screen.

curl -X POST https://api.beta.suby.fi/v3/payments/off-session \
  -H "Content-Type: application/json" \
  -H "X-Suby-Api-Key: sk_sandbox_your_key" \
  -d '{
    "offSession": true,
    "customer": { "id": "cus_abc123" },
    "customerPaymentMethodId": "pi_abc123",
    "productId": "pro_abc123",
    "priceCents": "1250",
    "displayName": "April usage"
  }'

A card charge with the buyer present is refused here. Collecting a card needs a page that renders card fields, and that page is ours · so there is no way to hand this endpoint a card token, and no card data ever reaches your servers.

Full API reference

Every parameter and response field.

Overview

Endpoints

Charge without a hosted page

Full API reference

​Charge without a hosted page

Full API reference

Charge without a hosted page