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

# Payments API

> Payment processing API for cryptocurrency

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

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

<CardGroup cols={2}>
  <Card title="API Reference" icon="book-open" href="/api-reference/introduction" />

  <Card title="Webhooks" icon="bolt" href="/payments/webhooks" />
</CardGroup>

## Creating a Payment

Send a `POST` request to create a new payment. The `currency` and `amount` fields are required.

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

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

```json theme={null}
{
  "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.

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

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

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

```json theme={null}
{
  "data": { ... },
  "message": null,
  "errors": null
}
```

### Error responses

**400 - Validation Error:**

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

**401 - Unauthorized:**

```json theme={null}
{
  "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?

<Card title="Support" icon="life-ring" href="mailto:payments@forebit.io">
  Get help from our payment team
</Card>