Introduction

Welcome to the Suby.fi Merchant API documentation. This API is designed for merchants who want to integrate Suby's one time & subscription payment system into their online business.

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:

1. Create a Suby.fi Account: Sign up at https://app.suby.fi

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

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