# 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.
- [Migrating from v2](https://docs.suby.fi/v3-beta/migration): Endpoint-by-endpoint mapping from the legacy `/api/*` surface to `/v3/*`.

## 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.
- [Changelog](https://docs.suby.fi/v3-beta/changelog): Notable changes to the v3 API.

## 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):

- Payments: `POST /v3/payments`, `GET /v3/payments`, `GET /v3/payments/{id}`, `GET /v3/payments/{id}/receipt`, `GET /v3/payments/{id}/receipt.pdf`, `POST /v3/payments/{id}/capture`, `POST /v3/payments/{id}/void`
- Subscriptions: `POST /v3/subscriptions`, `GET /v3/subscriptions/{id}`, `POST /v3/subscriptions/{id}/cancel`
- Products: `POST /v3/products`, `GET /v3/products`, `GET /v3/products/{id}`, `PATCH /v3/products/{id}`, `DELETE /v3/products/{id}`, `GET /v3/products/{id}/analytics`
- Customers: `POST /v3/customers`, `GET /v3/customers`, `GET /v3/customers/{id}`, `PATCH /v3/customers/{id}`, `GET /v3/customers/{id}/analytics`
- Payment methods: `GET /v3/customers/{id}/payment-methods`, `DELETE /v3/customers/{id}/payment-methods/{pmId}`
- Setup intents: `POST /v3/setup-intents`
- Checkout sessions: `POST /v3/checkout/sessions`, `GET /v3/checkout/sessions/{id}`
- Checkout settings: `GET /v3/checkout-settings`, `PATCH /v3/checkout-settings`
- Webhook endpoints: `POST /v3/webhook-endpoints`, `GET /v3/webhook-endpoints`, `GET /v3/webhook-endpoints/{id}`, `PATCH /v3/webhook-endpoints/{id}`, `DELETE /v3/webhook-endpoints/{id}`, `POST /v3/webhook-endpoints/{id}/rotate-secret`
- Analytics: `GET /v3/analytics`
- Health: `GET /health`

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