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

# Introduction

> Legacy v2 API — accept card and crypto payments with Suby.fi

<Info>
  You are viewing the **legacy v2** documentation. New integrations should use
  **[v3-beta](/v3-beta/introduction)**, which is RESTful (plural resources,
  Stripe-style) and adds saved payment methods, setup intents, hosted checkout
  sessions, and a unified balance. v2 remains available for existing merchants.
</Info>

### What is Suby.fi?

Suby.fi is a payment platform for one-time and subscription payments. Accept credit/debit card payments and cryptocurrency payments, with pricing in USD or EUR.

Whether you're running a SaaS business, online community, or digital product service, Suby provides the infrastructure to handle payments, manage subscriptions, and grant access to your customers automatically.

### Payment Methods

Suby.fi supports three payment configurations depending on your needs:

| Configuration     | Description                                               | Use Case                                              |
| ----------------- | --------------------------------------------------------- | ----------------------------------------------------- |
| **Card only**     | Accept credit/debit card payments                         | Traditional SaaS, digital products                    |
| **Crypto only**   | Accept on-chain payments (USDC, USDT, ETH, SOL, and more) | Web3-native products, global payments without banking |
| **Card + Crypto** | Accept both payment methods on the same product           | Maximum reach, let customers choose how to pay        |

You configure payment methods per product using the `paymentMethods` field: `["CARD"]`, `["CRYPTO"]`, or `["CARD", "CRYPTO"]`.

### Supported Currencies

Products can be priced in **USD** or **EUR**. The currency is set at product creation via the `currency` field.

* **Card payments**: Charged in the product's currency (USD or EUR)
* **Crypto payments**: Converted automatically using real-time oracle rates (Pyth)

### Supported Chains & Assets

| Chain    | Chain ID | Assets          |
| -------- | -------- | --------------- |
| Ethereum | 1        | USDC, USDT, ETH |
| Base     | 8453     | USDC, ETH       |
| Arbitrum | 42161    | USDC, ETH       |
| BSC      | 56       | USDC, USDT, BNB |
| Solana   | 101      | USDC, SOL       |

You can restrict accepted chains and assets per product, or leave them open to accept all available options.

### Authentication

Include your API key in the `X-Suby-Api-Key` header:

```
X-Suby-Api-Key: sk_live_your_key_here
```

Generate your merchant API key from your [dashboard settings](https://app.suby.fi/dashboard/settings). Store it securely — it is only shown once.

### API Endpoints Overview

| Method   | Endpoint                            | Description                             |
| -------- | ----------------------------------- | --------------------------------------- |
| `POST`   | `/api/product/create`               | Create a product                        |
| `PATCH`  | `/api/product/:productId`           | Update a product                        |
| `GET`    | `/api/product/all`                  | List all products                       |
| `GET`    | `/api/product/:productId`           | Get product by ID                       |
| `POST`   | `/api/payment/create`               | Create a one-time payment               |
| `GET`    | `/api/payment/`                     | List one-time payments                  |
| `GET`    | `/api/payment/:paymentId`           | Get payment by ID                       |
| `POST`   | `/api/subscription/create`          | Create a subscription payment           |
| `GET`    | `/api/subscription/`                | List subscriptions                      |
| `GET`    | `/api/subscription/:subscriptionId` | Get subscription by ID                  |
| `DELETE` | `/api/subscription/:subscriptionId` | Cancel a subscription                   |
| `POST`   | `/api/refund/:paymentId`            | Refund a card payment (full or partial) |
| `POST`   | `/api/discount/create`              | Create a discount code                  |
| `GET`    | `/api/customer`                     | List customers                          |
| `GET`    | `/api/customer/search?email=`       | Find customer by email                  |
| `GET`    | `/api/customer/:customerId`         | Get customer by ID                      |

All endpoints require the `X-Suby-Api-Key` header. Full request/response schemas are in the [API Reference](/v2/api-reference/overview).

### Customer Identity

Every customer has a stable `customerId`, returned by the `GET /api/customer` endpoints and on every payment/subscription response and webhook. It never changes even if the customer updates their email, so it is the reliable key for long-term account history.

When creating a payment or subscription, pass `customerId` to link an existing customer (it takes precedence over `customerEmail`), or `customerEmail` the first time you see a customer — then store the returned `customerId` for next time. Omit both and the hosted checkout page collects the email at pay time.

### Idempotent Refunds

`POST /api/refund/:paymentId` accepts an optional `Idempotency-Key` header. Retry a timed-out refund with the **same key** and the original result is replayed (`Idempotency-Replayed: true`) instead of refunding twice — essential for partial refunds, which are otherwise legitimately repeatable. See the [API Reference](/v2/api-reference/introduction) for details.

### Webhook Events

Suby.fi sends signed webhooks to notify your server about payment lifecycle events.

**Payment events:** `CHECKOUT_INITIATED`, `CHECKOUT_SUCCESS`, `PAYMENT_SUCCESS`, `PAYMENT_FAILED`, `PARTIAL_REFUNDED`, `PAYMENT_REFUNDED`, `PAYMENT_CHARGEBACK`, `PAYMENT_SETTLED`.

**Subscription events:** `SUBSCRIPTION_CREATED`, `SUBSCRIPTION_RENEWED`, `SUBSCRIPTION_PAST_DUE`, `SUBSCRIPTION_EXPIRED`.

#### Recommended Access Granting Strategy

| Payment Method | Grant access on    | Revoke access on                                                |
| -------------- | ------------------ | --------------------------------------------------------------- |
| **Card**       | `CHECKOUT_SUCCESS` | `PAYMENT_FAILED`, `PAYMENT_REFUNDED`, or `SUBSCRIPTION_EXPIRED` |
| **Crypto**     | `PAYMENT_SUCCESS`  | `PAYMENT_FAILED` or `SUBSCRIPTION_EXPIRED`                      |

#### Verifying Webhook Signatures

Every webhook is signed with HMAC-SHA256. The signature is sent in the `X-Webhook-Signature` header as `v1=<hex>`.

```typescript theme={null}
const signedPayload = `${timestamp}.${rawBody}`;
const expected = crypto
  .createHmac("sha256", webhookSecret)
  .update(signedPayload)
  .digest("hex");

const isValid = signature === `v1=${expected}`;
```

Reject webhooks with a timestamp older than 5 minutes to prevent replay attacks.

### Quick Example

```bash theme={null}
# 1. Create a product
curl -X POST https://api.suby.fi/api/product/create \
  -H "Content-Type: application/json" \
  -H "X-Suby-Api-Key: sk_live_your_key" \
  -d '{
    "name": "Pro Plan",
    "priceCents": "999",
    "currency": "EUR",
    "frequencyInDays": 30,
    "platform": "WEB",
    "paymentMethods": ["CARD", "CRYPTO"],
    "acceptedChains": [8453, 42161]
  }'

# 2. Create a payment (customerEmail is OPTIONAL)
curl -X POST https://api.suby.fi/api/payment/create \
  -H "Content-Type: application/json" \
  -H "X-Suby-Api-Key: sk_live_your_key" \
  -d '{
    "productId": "your_product_id",
    "customerEmail": "customer@example.com",
    "externalRef": "order_123",
    "successUrl": "https://your-app.com/success",
    "cancelUrl": "https://your-app.com/cancel"
  }'

# 3. Redirect customer to paymentUrl → 4. Receive webhooks → grant access
```