What is Suby.fi?

Suby.fi is a comprehensive one time & subscription payment platform that enables you to accept credit/debit card and cryptocurrency payments. 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.

Who is this API for?

This API is intended for merchants who want to:

Accept fiat and crypto payments for one time & subscription
Automate subscription management
Integrate payments into their existing web applications
Receive real-time notifications about payment events
Build custom one time & subscription flows

Getting Started

Before you begin integrating the API, you'll need:

Create a Suby.fi Account: Sign up at https://app.suby.fi
Generate Your API Key:
- Navigate to Dashboard Settings
- Generate your merchant API key
- Store it securely - it will only be shown once
- Use this key in the X-Suby-Api-Key header for all API requests
Create a Plan:
- Set up your one time or subscription plans from the dashboard
- Configure pricing, payment methods, and accepted currencies
- Note your plan IDs for API integration

Webhook Events

Suby.fi sends webhooks to notify your server about important events. Configure your webhook URL in the dashboard settings.

Event Type	When It's Sent	Use Case
`CHECKOUT_INITIATED`	When a customer starts the payment process	Track checkout conversions, send analytics
`CHECKOUT_SUCCESS`	Emitted after a successful card checkout and payment authorization. This webhook is only sent for card payments and is never sent for crypto payments.	Grant access for card payments, update order status, send confirmation emails
`PAYMENT_SUCCESS`	When a payment is successfully authorized by the payment provider or confirmed on-chain. Final settlement for card payments may occur at a later date.	Grant access to your service for crypto payments. For card payments, access should already be granted at checkout success.
`PAYMENT_FAILED`	Emitted when a payment fails after processing. For crypto payments, this indicates an on-chain failure. For card payments, this may occur during settlement and can be emitted after a `CHECKOUT_SUCCESS` event.	Notify the customer, handle retries or fallback flows, update order status

Sample Webhook Server

We provide a complete example server that demonstrates webhook reception and signature verification:

Repository: https://github.com/hunterlabs-fi/suby-test-server

This example includes:

Webhook signature verification
Event handling for all webhook types
Express.js implementation
TypeScript support

Key Features

Multi-Currency Support: Accept payments in USDC, USDT, ETH, SOL, and more
Automatic Renewals: Handle recurring subscriptions automatically
Webhook Notifications: Receive real-time updates about payment events
Secure Authentication: API key-based authentication with SHA256 hashing
Metadata Support: Attach custom data to payments for your internal tracking