# Suby.fi Merchant API

> Suby.fi is a payment platform for one-time and subscription payments. Merchants accept credit/debit cards + APMs and cryptocurrency (BTC/SOL/EVM, settled in USDC/EURC on Base), priced in USD or EUR, and automate post-payment access management. The current API is **v3** (RESTful, Stripe-style), served under the `/v3` prefix at `https://api.beta.suby.fi`. Authentication is an API key in the `X-Suby-Api-Key` header (`sk_live_…` / `sk_sandbox_…`).

## Getting started (v3-beta)

- [Introduction](https://docs.suby.fi/v3-beta/introduction): What Suby.fi is, what's new in v3, supported currencies/chains, environments.
- [Authentication](https://docs.suby.fi/v3-beta/authentication): API keys, LIVE vs sandbox (prefix-derived), rate limiting.
- [Quickstart](https://docs.suby.fi/v3-beta/quickstart): Create a product and take your first payment.

## Core concepts (v3-beta)

- [Webhooks](https://docs.suby.fi/v3-beta/webhooks): Event catalog (`payment.succeeded`, `subscription.renewed`, …), delivery headers, and HMAC-SHA256 signature verification.
- [Errors & responses](https://docs.suby.fi/v3-beta/errors): Response envelope, cursor pagination, HTTP status codes, and error-code catalog.

## API reference (v3-beta)

- [API Reference overview](https://docs.suby.fi/v3-beta/api-reference/overview): Base URL, auth, conventions, and resource groups.
- [OpenAPI spec (YAML)](https://docs.suby.fi/v3-beta/api-reference/openapi.yaml): Full machine-readable OpenAPI 3.1 definition of every v3 endpoint.

Endpoints (all under `https://api.beta.suby.fi`, `X-Suby-Api-Key` required):

- Checkout: `POST /v3/checkout/sessions`, `GET /v3/checkout/sessions/{token}` · the only place a card is collected. `mode=payment` takes a one-time charge, `mode=subscription` opens a subscription and bills its first cycle (a recurring product sold as `payment` is charged once and never renews), `mode=setup` stores a card without charging.
- Crypto (headless, rendered in the merchant's own site): `GET /v3/crypto/assets`, `GET /v3/crypto/quote`, `POST /v3/crypto/charges` · returns a deposit address or wallet calldata; poll the payment for `deposit.confirmations`. Settlement routing is an account setting.
- Payments: `POST /v3/payments/off-session` (debit of a stored card; a charge with the buyer present is refused), `GET /v3/payments`, `GET /v3/payments/{id}`, `GET /v3/payments/{id}/receipt`, `GET /v3/payments/{id}/receipt.pdf`, `POST /v3/payments/{id}/refund`
- Subscriptions: `GET /v3/subscriptions`, `GET /v3/subscriptions/{id}`, `POST /v3/subscriptions/{id}/change-plan`, `POST /v3/subscriptions/{id}/cancel` · opened by a checkout session, not created here
- Products: `POST /v3/products`, `GET /v3/products`, `GET /v3/products/{id}`, `PATCH /v3/products/{id}`, `POST /v3/products/{id}/archive`, `POST /v3/products/{id}/unarchive`
- Customers: `POST /v3/customers`, `GET /v3/customers`, `GET /v3/customers/{id}`, `PATCH /v3/customers/{id}`
- Payment methods: `GET /v3/customers/{id}/payment-methods`, `DELETE /v3/customers/{id}/payment-methods/{pmId}` · created by a checkout session, never by this API
- Discount codes: `POST /v3/discount-codes`, `GET /v3/discount-codes`, `GET /v3/discount-codes/{id}`, `PATCH /v3/discount-codes/{id}`, `DELETE /v3/discount-codes/{id}`
- Licences (API key required, scoped to your account · your backend relays, your customer's software never holds `sk_live`): `POST /v3/licenses/validate`, `/activate`, `/deactivate`

Analytics, checkout branding, webhook-endpoint management and post-payment access configuration are dashboard-only. Webhooks are still emitted; only choosing where they go left the API.

## Optional (legacy v2)

- [v2 Introduction](https://docs.suby.fi/v2/introduction): Legacy `/api/*` API · kept for existing merchants; new integrations should use v3.
- [v2 API Reference overview](https://docs.suby.fi/v2/api-reference/overview): Legacy endpoint reference.
- [v2 OpenAPI spec (YAML)](https://docs.suby.fi/v2/api-reference/openapi.yaml): Machine-readable legacy definition.