> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.suby.fi/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Create a product and take your first payment with the v3 API.

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

<Steps>
  <Step title="Create a product">
    Define what you sell. Omit `recurringInterval` for a one-time product.

    ```bash theme={null}
    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.
  </Step>

  <Step title="Create a customer (optional)">
    You can attach an existing `customerId`, or let the payment create one inline
    via `customerData`. To create one explicitly:

    ```bash theme={null}
    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" }'
    ```
  </Step>

  <Step title="Take a payment">
    The simplest integration is a **hosted checkout session** — mint a `cs_…`
    token and redirect the buyer to its `url`.

    ```bash theme={null}
    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.
  </Step>

  <Step title="Register a webhook endpoint">
    Get notified as the payment progresses.

    ```bash theme={null}
    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](/v3-beta/webhooks).
  </Step>

  <Step title="Grant access">
    In your webhook handler, verify the signature and grant access on the
    right event ([recommended strategy](/v3-beta/webhooks#access-granting)).
  </Step>
</Steps>

## 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`.

```bash theme={null}
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" }
  }'
```

<Card title="Full API reference" icon="code" href="/v3-beta/api-reference/overview">
  Every parameter and response field, endpoint by endpoint.
</Card>