Skip to main content

​
Overview

This guide walks you through adding Forebit Payments to your product: create a payment, redirect to checkout, receive webhooks, and confirm the order.

​
Prerequisites

  • Business ID and API key from Payments → Settings → Developer
  • Webhook signing secret (from Developer → Webhooks)
  • Server capable of receiving webhooks (public URL for prod)

​
1) Create a Payment

Send a POST request to create a payment. Only currency and amount are required. 
curl -X POST https://prod-payments-api.forebit.io/v1/businesses/{businessId}/payments \
  -H "Authorization: Bearer YOUR_PAYMENTS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "currency": "USD",
    "amount": 25.00,
    "name": "Order #1234",
    "description": "Internal note for your team",
    "customerEmail": "customer@example.com",
    "redirectUrl": "https://yoursite.com/thank-you",
    "notifyUrl": "https://yoursite.com/webhooks/forebit",
    "metadata": {
      "orderId": "1234"
    }
  }'
FieldTypeRequiredDescription
currencystringYesISO 4217 currency code (e.g. USD, EUR)
amountnumberYesPayment amount (minimum 0.5)
namestringNoDisplay name shown to customer on checkout
descriptionstringNoInternal description, not visible to customers
customerEmailstring (email)NoCustomer email for receipts and status updates
redirectUrlstring (URI)NoURL to redirect the customer after payment
notifyUrlstringNoWebhook URL for this specific payment
metadataobjectNoArbitrary key-value string pairs stored with the payment
paymentMethodsobjectNoRestrict which payment methods are available
feeTransfersarrayNoFee transfer configuration
The response contains the payment id (UUID) and a hosted checkout url: 
{
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "url": "https://pay.forebit.io/payment/a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  },
  "message": null,
  "errors": null
}

Create Payment (Playground)

​
Available Payment Methods

Control which cryptocurrencies your customer can use by passing the paymentMethods object. Each key is a charge type, and the value is an array of allowed coin identifiers. 
{
  "paymentMethods": {
    "FOREBIT_CRYPTO": ["BITCOIN", "ETHEREUM", "SOLANA"],
    "CONTRACT_CRYPTO": ["CONTRACT_ERC20_USDT", "CONTRACT_ERC20_USDC"]
  }
}

​
Charge types

TypeDescription
FOREBIT_CRYPTONative coins and tokens via Forebit wallets
CONTRACT_CRYPTOERC-20 tokens via smart contract
CONTRACT_TRXTRC-20 tokens via smart contract
NONENo crypto payment method

​
Supported coins

FOREBIT_CRYPTO: 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, SOLANA, SOL_TETHER, SOL_USD_COIN, TON CONTRACT_CRYPTO: CONTRACT_ERC20_ETH, CONTRACT_ERC20_USDT, CONTRACT_ERC20_USDC CONTRACT_TRX: CONTRACT_TRC20_TRX, CONTRACT_TRC20_USDT, CONTRACT_TRC20_USDC If paymentMethods is omitted, all configured methods for your business are enabled.

​
2) Redirect to Checkout

After creating a payment, redirect the customer to the url returned in the response. This is a Forebit-hosted checkout page where the customer selects a cryptocurrency and completes the payment. 
// After creating the payment
window.location.href = response.data.url;

​
3) Handle Webhook Events

Configure a webhook endpoint on your server to receive payment status updates. Verify signatures with Svix using the raw request body. The webhook payload includes the payment data with these key status transitions:
StatusMeaning
AWAITING_PAYMENTPayment created, waiting for customer
PENDINGPayment detected, awaiting confirmation
PROCESSINGPayment is being processed
UNDERPAIDCustomer sent less than required
COMPLETEDPayment confirmed and completed
FAILEDPayment failed
CANCELLEDPayment was cancelled
EXPIREDPayment expired before completion
For full event list, payload schemas, and code examples, see the Webhooks guide.

Webhooks Guide

Verification reference: Svix — Verifying Payloads

​
4) Verify Payment Status

After a webhook confirms completion, update your order and show a success screen. You can also fetch the payment directly to verify its current status: 
curl https://prod-payments-api.forebit.io/v1/businesses/{businessId}/payments/{paymentId} \
  -H "Authorization: Bearer YOUR_PAYMENTS_API_KEY"
The response includes the full payment record with status, endAmount, currency, timeline, customer, charge details, and metadata. 
{
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "endAmount": 25.00,
    "currency": "USD",
    "status": "COMPLETED",
    "createdAt": "2025-01-15T10:30:00Z",
    "expiresAt": "2025-01-15T11:30:00Z",
    "selectedPaymentMethod": "FOREBIT_CRYPTO",
    "forebitCryptoCharge": {
      "amount": 0.00025,
      "coinName": "BITCOIN",
      "exchangeRate": 100000.00,
      "isUnderpaid": false,
      "address": "bc1q..."
    },
    "metadata": {
      "orderId": "1234"
    },
    "netAmountUsd": 24.50,
    "forebitFee": 0.50
  },
  "message": null,
  "errors": null
}

​
Error Handling

API errors follow the RFC 7807 ProblemDetails format: 
{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
  "title": "Bad Request",
  "status": 400,
  "detail": "Validation failed"
}
StatusMeaning
400Invalid parameters or validation error
401Invalid or missing API key
403Insufficient permissions for this business
404Payment or business not found

​
Testing

  • Create small‑amount test payments (minimum 0.5 in your chosen currency)
  • Use Svix CLI or dashboard to replay webhooks to your endpoint

​
Next Steps

Webhooks

API Reference

Guide for AI Agents

Full integration context for Claude, Cursor, and Codex