Introduction

1. Create a product (dashboard or API)
2. Initiate a payment → receive a paymentUrl
3. Redirect your customer to the paymentUrl
4. Receive webhooks as the payment progresses
5. Grant access based on webhook events

interface PaymentWebhookEvent {
  id: string;                    // Unique event ID (evt_xxx)
  type: "CHECKOUT_INITIATED" | "CHECKOUT_SUCCESS" | "PAYMENT_SUCCESS" | "PAYMENT_FAILED" | "PAYMENT_REFUNDED" | "PAYMENT_SETTLED";
  createdAt: string;             // ISO 8601 timestamp
  data: {
    payment: {
      id: string;
      status: string;
      subscriptionId: string | null;
      productId: string | null;
      valueUsd: string | null;   // Amount in cents
      priceCents: string | null; // Price in cents (custom price products)
      currency: string | null;   // "USD" or "EUR"
      vatAmountCents: number | null;    // VAT amount in cents (card only)
      totalAmountCents: number | null;  // Total including VAT (card only)
      txHash: string | null;     // Blockchain transaction hash (crypto only)
      source: string | null;     // "CRYPTO" or "FIAT"
      customerEmail: string | null;
      customerDiscordId: string | null;
      customerTelegramId: string | null;
      customerDiscordUsername: string | null;
      customerTelegramUsername: string | null;
    };
    context: {
      externalRef: string | null;
      metadata: Record<string, any> | null;
      successUrl: string | null;
      cancelUrl: string | null;
    };
  };
}

interface PaymentSettledWebhookEvent {
  id: string;                    // Unique event ID (evt_xxx)
  type: "PAYMENT_SETTLED";
  createdAt: string;             // ISO 8601 timestamp
  data: {
    payouts: Array<{
      id: string;                // Payout ID
      payoutAmountCents: number; // Total payout amount in cents
      currency: string;          // "USD" or "EUR"
      paidOutAt: string;         // ISO 8601 timestamp
    }>;
    payments: Array<{
      id: string;
      payoutId: string;          // ID of the payout this payment belongs to
      productId: string | null;
      subscriptionId: string | null;
      priceCents: string | null;
      currency: string | null;
      grossAmountCents: number | null;
      merchantNetCents: number | null;
      customerEmail: string | null;
      customerDiscordId: string | null;
      customerTelegramId: string | null;
      externalRef: string | null;
    }>;
  };
}

interface SubscriptionWebhookEvent {
  id: string;                    // Unique event ID (evt_xxx)
  type: "SUBSCRIPTION_PAST_DUE" | "SUBSCRIPTION_EXPIRED";
  createdAt: string;             // ISO 8601 timestamp
  data: {
    subscription: {
      id: string;
      status: string;
      productId: string;
      expiresAt: string | null;
    };
    lastPayment: {
      id: string;
      status: string;
      priceCents: string | null;
      currency: string | null;
      createdAt: string;
    } | null;
    customer: {
      email: string | null;
      discordId: string | null;
      telegramId: string | null;
      discordUsername: string | null;
      telegramUsername: string | null;
    };
    context: {
      externalRef: string | null;
      metadata: Record<string, any> | null;
    };
  };
}

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

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

# 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 (one-time product)
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",
    "metadata": { "userId": "usr_456" },
    "successUrl": "https://your-app.com/success",
    "cancelUrl": "https://your-app.com/cancel"
  }'

# Or for a subscription product:
# curl -X POST https://api.suby.fi/api/subscription/create \
#   -H "Content-Type: application/json" \
#   -H "X-Suby-Api-Key: sk_live_your_key" \
#   -d '{ "productId": "your_product_id", "customerEmail": "customer@example.com" }'

# Response:
# {
#   "success": true,
#   "data": {
#     "paymentId": "pay_abc123",
#     "paymentUrl": "https://app.suby.fi/pay/pay_abc123"
#   }
# }

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