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

# Forebit Payments Webhook Documentation

> How to receive and validate payment webhooks using Svix

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

```json theme={null}
{
  "EventType": "PAYMENT_COMPLETED",
  "ForPaymentEvents": {
    /* payment data (PaymentForWebhookResponse) */
  }
}
```

### BaseWebhookResponse

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

### GetPaymentResponse (base)

```typescript theme={null}
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)

```typescript theme={null}
interface PaymentForWebhookResponse extends GetPaymentResponse {
  BusinessId: number;
  RedirectUrl?: string | null;
}
```

### Nested types

```typescript theme={null}
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

```typescript theme={null}
type PaymentStatus =
  | 'AWAITING_PAYMENT'
  | 'PENDING'
  | 'PROCESSING'
  | 'UNDERPAID'
  | 'COMPLETED'
  | 'FAILED'
  | 'CANCELLED'
  | 'EXPIRED';
```

### PaymentMethod

```typescript theme={null}
type PaymentMethod = 'FOREBIT_CRYPTO' | 'CONTRACT_CRYPTO' | 'CONTRACT_TRX' | 'NONE';
```

### Network

```typescript theme={null}
type Network = 'ETHEREUM' | 'TRON' | 'BTC' | 'LTC' | 'SOLANA';
```

### CryptoCoinName

```typescript theme={null}
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

```typescript theme={null}
type IpConnectionType =
  | 'RESIDENTIAL'
  | 'BUSINESS'
  | 'WIRELESS'
  | 'VPN'
  | 'SOCKS'
  | 'COMPROMISED_SERVER'
  | 'Unknown';
```

### Example — PAYMENT\_COMPLETED

```json theme={null}
{
  "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](https://docs.svix.com/receiving/verifying-payloads/how).

## Monitoring & debugging

Use `/v1/businesses/{businessId}/payments/{paymentId}/webhook-logs` to retrieve delivery history, including:

* Delivery status

* Attempt timestamps

* HTTP response codes

* Response bodies