Introduction

You are viewing the legacy v2 documentation. New integrations should use v3-beta, 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.

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

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

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

# 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

Get started

Sandbox/Test Mode

Features

Merchant of record facilitator

Payment flows & fees

For Customers

Legal

What is Suby.fi?

Payment Methods

Supported Currencies

Supported Chains & Assets

Authentication

API Endpoints Overview

Customer Identity

Idempotent Refunds

Webhook Events

Recommended Access Granting Strategy

Verifying Webhook Signatures

Quick Example

​What is Suby.fi?

​Payment Methods

​Supported Currencies

​Supported Chains & Assets

​Authentication

​API Endpoints Overview

​Customer Identity

​Idempotent Refunds

​Webhook Events

​Recommended Access Granting Strategy

​Verifying Webhook Signatures

​Quick Example

What is Suby.fi?

Payment Methods

Supported Currencies

Supported Chains & Assets

Authentication

API Endpoints Overview

Customer Identity

Idempotent Refunds

Webhook Events

Recommended Access Granting Strategy

Verifying Webhook Signatures

Quick Example