Payments API - Forebit Developer Hub

Getting Started with Payments API

Welcome! This guide will help you get started quickly.

Authentication

All API requests require a Bearer token in the Authorization header.

Authorization: Bearer YOUR_PAYMENTS_API_KEY

Base URL

https://prod-payments-api.forebit.io

All requests must use HTTPS.

Core Endpoints

The API provides four operations scoped to a business:

Method	Endpoint	Description
`GET`	`/v1/businesses/{businessId}/payments`	Fetch a paginated set of payments
`POST`	`/v1/businesses/{businessId}/payments`	Create a new payment
`GET`	`/v1/businesses/{businessId}/payments/{paymentId}`	Retrieve a single payment’s full record
`PUT`	`/v1/businesses/{businessId}/payments/{paymentId}/note`	Set or update an internal note on a payment

API Reference

Webhooks

Creating a Payment

Send a POST request to create a new payment. The currency and amount fields 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 order note",
    "customerEmail": "customer@example.com",
    "redirectUrl": "https://yoursite.com/thank-you",
    "notifyUrl": "https://yoursite.com/webhooks/forebit",
    "metadata": {
      "orderId": "1234",
      "plan": "premium"
    }
  }'

CreatePaymentRequest fields

Field	Type	Required	Description
`currency`	string	Yes	ISO 4217 currency code (e.g. `USD`, `EUR`)
`amount`	number	Yes	Payment amount (minimum `0.5`)
`name`	string	No	Display name shown to customer on checkout
`description`	string	No	Internal description, not visible to customers
`customerEmail`	string (email)	No	Customer email for receipts and status updates
`customerIp`	string	No	Customer IP address. Auto-detected from checkout page visit if omitted
`customerUserAgent`	string	No	Customer user-agent. Auto-detected from checkout page visit if omitted
`redirectUrl`	string (URI)	No	URL to redirect the customer after payment
`notifyUrl`	string	No	Webhook URL for this specific payment
`metadata`	object	No	Arbitrary key-value string pairs stored with the payment
`paymentMethods`	object	No	Restrict which payment methods are available to the customer
`feeTransfers`	array	No	Fee transfer configuration

Payment methods

You can restrict which cryptocurrencies a customer can use by specifying the paymentMethods object. Each key is a charge type, and the value is an array of allowed coin names.

{
  "paymentMethods": {
    "FOREBIT_CRYPTO": ["BITCOIN", "ETHEREUM", "SOLANA"],
    "CONTRACT_CRYPTO": ["CONTRACT_ERC20_USDT", "CONTRACT_ERC20_USDC"]
  }
}

Charge types: FOREBIT_CRYPTO, CONTRACT_CRYPTO, CONTRACT_TRX, NONE

Successful response

{
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "url": "https://pay.forebit.io/payment/a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  },
  "message": null,
  "errors": null
}

The url is the hosted checkout page you redirect your customer to.

Retrieving a Payment

Fetch the full record for a single payment including customer info, event timeline, on-chain transaction data, and fee details.

curl https://prod-payments-api.forebit.io/v1/businesses/{businessId}/payments/{paymentId} \
  -H "Authorization: Bearer YOUR_PAYMENTS_API_KEY"

GetPaymentResponse fields

Field	Type	Description
`id`	string (UUID)	Payment identifier
`name`	string	Display name
`description`	string	Internal description
`endAmount`	number	Final payment amount
`prePaymentAmount`	number	Amount before payment processing
`currency`	string	ISO 4217 currency code
`status`	PaymentStatus	Current payment status
`createdAt`	date-time	When the payment was created
`expiresAt`	date-time	When the payment expires
`timeline`	array	Status change history
`customer`	object	Customer details including email and IP info
`metadata`	object	Custom key-value pairs
`selectedPaymentMethod`	PaymentMethod	Method chosen by the customer
`forebitCryptoCharge`	object	Forebit crypto charge details (if applicable)
`contractCharge`	object	Contract charge details (if applicable)
`forebitFee`	number	Fee amount
`note`	string	Internal note
`netAmountUsd`	number	Net amount in USD

Listing Payments

Fetch a paginated, filterable list of payments for a business.

curl "https://prod-payments-api.forebit.io/v1/businesses/{businessId}/payments?PageSize=20&statuses=COMPLETED&statuses=PENDING" \
  -H "Authorization: Bearer YOUR_PAYMENTS_API_KEY"

Query parameters

Parameter	Type	Description
`PageNumber`	integer	Page number for pagination
`PageSize`	integer	Number of results per page
`fromTime`	date-time	Start of date range filter
`toTime`	date-time	End of date range filter
`statuses`	array	Filter by payment statuses
`cryptoCoins`	array	Filter by cryptocurrency
`fromAmount`	number	Minimum amount filter
`toAmount`	number	Maximum amount filter
`searchString`	string	Free-text search across description, name, note, or customer email
`onBehalfOfBusinessId`	integer	Scope results to a specific on-behalf-of business

Updating a Payment Note

Set or overwrite the internal note attached to a payment (max 256 characters). Notes are only visible to your team.

curl -X PUT https://prod-payments-api.forebit.io/v1/businesses/{businessId}/payments/{paymentId}/note \
  -H "Authorization: Bearer YOUR_PAYMENTS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "note": "Customer requested expedited processing"
  }'

Payment Statuses

Payments progress through these statuses:

Status	Description
`AWAITING_PAYMENT`	Payment created, waiting for customer to pay
`PENDING`	Payment detected, awaiting confirmation
`PROCESSING`	Payment is being processed
`UNDERPAID`	Customer sent less than the required amount
`COMPLETED`	Payment confirmed and completed
`FAILED`	Payment failed
`CANCELLED`	Payment was cancelled
`EXPIRED`	Payment expired before completion

Supported Cryptocurrencies

Coin	Identifier
Bitcoin	`BITCOIN`
Ethereum	`ETHEREUM`
Litecoin	`LITECOIN`
Bitcoin Cash	`BITCOIN_CASH`
USDC (ERC-20)	`ETH_USD_COIN`
USDT (ERC-20)	`ETH_TETHER`
Monero	`MONERO`
BNB	`BNB`
DAI (ERC-20)	`ETH_DAI`
Uniswap (ERC-20)	`ETH_UNISWAP`
MATIC (ERC-20)	`ETH_MATIC`
SHIB (ERC-20)	`ETH_SHIBA_INU`
APE (ERC-20)	`ETH_APE_COIN`
CRO (ERC-20)	`ETH_CRONOS`
BUSD (ERC-20)	`ETH_BUSD`
Tron	`TRON`
USDT (TRC-20)	`TRX_TETHER`
USDC (TRC-20)	`TRX_USD_C`
Solana	`SOLANA`
USDT (Solana)	`SOL_TETHER`
USDC (Solana)	`SOL_USD_COIN`
TON	`TON`
Contract ETH	`CONTRACT_ERC20_ETH`
Contract USDT (ERC-20)	`CONTRACT_ERC20_USDT`
Contract USDC (ERC-20)	`CONTRACT_ERC20_USDC`
Contract TRX	`CONTRACT_TRC20_TRX`
Contract USDT (TRC-20)	`CONTRACT_TRC20_USDT`
Contract USDC (TRC-20)	`CONTRACT_TRC20_USDC`

Networks: ETHEREUM, TRON, BTC, LTC, SOLANA

Handling Responses

All API responses follow a consistent structure:

Success response

{
  "data": { ... },
  "message": null,
  "errors": null
}

Error responses

400 - Validation Error:

{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
  "title": "Bad Request",
  "status": 400,
  "detail": "Validation failed"
}

401 - Unauthorized:

{
  "type": "https://tools.ietf.org/html/rfc7235#section-3.1",
  "title": "Unauthorized",
  "status": 401
}

403 - Forbidden and 404 - Not Found follow the same ProblemDetails format.

Need Help?

Support

Get help from our payment team

Getting Started

Guides

Endpoints

​Getting Started with Payments API

​Authentication

​Base URL

​Core Endpoints

API Reference

Webhooks

​Creating a Payment

​CreatePaymentRequest fields

​Payment methods

​Successful response

​Retrieving a Payment

​GetPaymentResponse fields

​Listing Payments

​Query parameters

​Updating a Payment Note

​Payment Statuses

​Supported Cryptocurrencies

​Handling Responses

​Success response

​Error responses

​Need Help?