Skip to main content

Documentation Index

Fetch the complete documentation index at: https://developer.forebit.io/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

Forebit Payments uses Svix to manage webhooks. Svix provides reliable delivery with automatic retries, signature validation, and detailed logs.

​
Webhook Events

​
Available events

  • PAYMENT_CREATED
  • PAYMENT_METHOD_SELECTED
  • PAYMENT_EXPIRED
  • PAYMENT_CANCELLED
  • PAYMENT_COMPLETED
  • PAYMENT_PENDING
  • PAYMENT_UNDERPAID

​
Webhook Payload Schema

​
Base payload

{
  "EventType": "PAYMENT_COMPLETED",
  "ForPaymentEvents": {
    /* payment data (PaymentForWebhookResponse) */
  }
}

​
BaseWebhookResponse

interface BaseWebhookResponse {
  // Event type as a string, one of the values listed above
  EventType: string;
  ForPaymentEvents?: PaymentForWebhookResponse | null;
}

​
GetPaymentResponse (base)

interface GetPaymentResponse {
  // Required
  Id: string; // Guid
  EndAmount: number;
  PrePaymentAmount: number;
  Currency: string;
  Status: PaymentStatus;
  CreatedAt: string; // ISO date
  ExpiresAt: string; // ISO date
  Timeline: TimelineForGetPaymentResponse[];

  // Optional
  Name?: string;
  Description?: string;
  Customer?: CustomerForGetPaymentResponse | null;
  Metadata?: Record<string, string> | null;
  SelectedPaymentMethod?: PaymentMethod | null;
  ForebitCryptoCharge?: ForebitCryptoChargeForGetPaymentResponse | null;
  ContractCharge?: ContractChargeForGetPaymentResponse | null;
  ForebitFee?: number | null; // 0 if null in webhooks
  Note?: string | null;
  OnBehalfOfBusinessId?: number | null; // not populated in current webhooks
  NetAmountUsd?: number | null; // not populated in current webhooks
}

​
PaymentForWebhookResponse (extends)

interface PaymentForWebhookResponse extends GetPaymentResponse {
  BusinessId: number;
  RedirectUrl?: string | null;
}

​
Nested types

interface CustomerForGetPaymentResponse {
  Id: number;
  Email: string;
  IpAddresses: CustomerIpDetailsResponse[];
}

interface CustomerIpDetailsResponse {
  City?: string | null;
  Ip: string;
  Country?: string | null;
  RiskScore?: number | null;
  ConnectionType: IpConnectionType;
  ISP?: string | null;
  DateCreated: string; // ISO date
}

interface TimelineForGetPaymentResponse {
  Time: string; // ISO date
  PaymentStatus: PaymentStatus;
}

interface ForebitCryptoChargeForGetPaymentResponse {
    Amount: number;
    CoinName: string;
    ExchangeRate: number;
    IsUnderpaid: boolean;
  Address: string;
  Transaction?: TransactionForGetPaymentResponse | null;
  WalletName: string;
}

interface TransactionForGetPaymentResponse {
      Amount: number;
      ToAddress: string;
      Id: string;
      Confirmations: number;
  BlockNumber?: string | null;
  Network?: Network | null;
  FromAddress?: string | null;
  TokenName?: CryptoCoinName | null;
}

interface ContractChargeForGetPaymentResponse {
    Amount: number;
    ExchangeRate: number;
    IsUnderpaid: boolean;
    Address: string;
  Transaction: TransactionForGetPaymentResponse;
    WalletName: string;
  CoinName: string;
}

​
PaymentStatus

type PaymentStatus =
  | 'AWAITING_PAYMENT'
  | 'PENDING'
  | 'PROCESSING'
  | 'UNDERPAID'
  | 'COMPLETED'
  | 'FAILED'
  | 'CANCELLED'
  | 'EXPIRED';

​
PaymentMethod

type PaymentMethod = 'FOREBIT_CRYPTO' | 'CONTRACT_CRYPTO' | 'CONTRACT_TRX' | 'NONE';

​
Network

type Network = 'ETHEREUM' | 'TRON' | 'BTC' | 'LTC' | 'SOLANA';

​
CryptoCoinName

type CryptoCoinName =
  | 'BITCOIN'
  | 'ETHEREUM'
  | 'LITECOIN'
  | 'BITCOIN_CASH'
  | 'ETH_USD_COIN'
  | 'ETH_TETHER'
  | 'MONERO'
  | 'BNB'
  | 'ETH_BUSD'
  | 'ETH_MATIC'
  | 'ETH_SHIBA_INU'
  | 'ETH_APE_COIN'
  | 'ETH_CRONOS'
  | 'ETH_DAI'
  | 'ETH_UNISWAP'
  | 'TRON'
  | 'TRX_TETHER'
  | 'TRX_USD_C'
  | 'UNKNOWN'
  | 'CONTRACT_ERC20_ETH'
  | 'CONTRACT_ERC20_USDT'
  | 'CONTRACT_ERC20_USDC'
  | 'CONTRACT_TRC20_TRX'
  | 'CONTRACT_TRC20_USDT'
  | 'CONTRACT_TRC20_USDC'
  | 'SOLANA'
  | 'SOL_TETHER'
  | 'SOL_USD_COIN'
  | 'TON';

​
IpConnectionType

type IpConnectionType =
  | 'RESIDENTIAL'
  | 'BUSINESS'
  | 'WIRELESS'
  | 'VPN'
  | 'SOCKS'
  | 'COMPROMISED_SERVER'
  | 'Unknown';

​
Example — PAYMENT_COMPLETED

{
  "EventType": "PAYMENT_COMPLETED",
  "ForPaymentEvents": {
    "Id": "78d1cc6a-2e46-421b-b03b-3c307bfbd1bc",
    "BusinessId": 1001,
    "Name": "sets sol",
    "Description": "",
    "EndAmount": 2,
    "PrePaymentAmount": 2,
    "Currency": "USD",
    "Status": "COMPLETED",
    "CreatedAt": "2025-08-14T09:18:56.295788Z",
    "ExpiresAt": "2025-08-14T09:48:56.295788Z",
    "Timeline": [
      { "Time": "2025-08-14T09:18:56.2958713Z", "PaymentStatus": "AWAITING_PAYMENT" },
      { "Time": "2025-08-14T09:20:40.2355434Z", "PaymentStatus": "PENDING" },
      { "Time": "2025-08-14T09:20:40.264907Z", "PaymentStatus": "COMPLETED" }
    ],
    "Customer": {
      "Id": 68,
      "Email": "test@test.com",
      "IpAddresses": [
        {
          "City": "Dangkao",
          "Ip": "45.118.76.153",
          "Country": "Cambodia",
          "RiskScore": 0,
          "ConnectionType": "BUSINESS",
          "ISP": "EZECOM CO., LTD.",
          "DateCreated": "2025-07-21T09:13:11.931385Z"
        }
      ]
    },
    "SelectedPaymentMethod": "FOREBIT_CRYPTO",
    "ForebitCryptoCharge": {
      "Amount": 0.009778,
      "CoinName": "SOLANA",
      "ExchangeRate": 204.54,
      "IsUnderpaid": false,
      "Address": "7w3H5G5L2zoubHnQ6QH1FV9bbMMp9L3ssvHZ9GiBaMkY",
      "Transaction": {
        "Amount": 0.009780429,
        "ToAddress": "7w3H5G5L2zoubHnQ6QH1FV9bbMMp9L3ssvHZ9GiBaMkY",
        "Id": "5GnGsAkVX7pbEpT2QxBVtMTjK4wKAgEYfDuZzAAyrmSVpG3f4bdjvygMMrN185bh2dwGa721rCip8qJxVkuDvwAb",
        "Confirmations": 1,
        "Network": "SOLANA",
        "FromAddress": "6oWVqV3tVJyr7BEi6CPiCqMp64Q1VV3MnvVwSzrVrmEZ",
        "TokenName": "SOLANA"
      },
      "WalletName": "NEWTEST"
    },
    "ForebitFee": 0.0
  }
}
Note: fields NetAmountUsd and OnBehalfOfBusinessId are currently not included in webhook payloads.

​
Webhook Validation

Use Svix official verification with the raw request body. Required headers: svix-id, svix-timestamp, svix-signature. See the step-by-step guide: How to Verify Webhooks with the Svix Libraries.

​
Monitoring & debugging

Use /v1/businesses/{businessId}/payments/{paymentId}/webhook-logs to retrieve delivery history, including:
  • Delivery status
  • Attempt timestamps
  • HTTP response codes
  • Response bodies