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

# Accept Payments on Your Site

> End‑to‑end guide to integrate Forebit Payments

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

```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 note for your team",
    "customerEmail": "customer@example.com",
    "redirectUrl": "https://yoursite.com/thank-you",
    "notifyUrl": "https://yoursite.com/webhooks/forebit",
    "metadata": {
      "orderId": "1234"
    }
  }'
```

| 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           |
| `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             |
| `feeTransfers`   | array          | No       | Fee transfer configuration                               |

The response contains the payment `id` (UUID) and a hosted checkout `url`:

```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
}
```

<Card title="Create Payment (Playground)" icon="bolt" href="/api-reference/endpoint/create-payment" />

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

```json theme={null}
{
  "paymentMethods": {
    "FOREBIT_CRYPTO": ["BITCOIN", "ETHEREUM", "SOLANA"],
    "CONTRACT_CRYPTO": ["CONTRACT_ERC20_USDT", "CONTRACT_ERC20_USDC"]
  }
}
```

### Charge types

| Type              | Description                                 |
| ----------------- | ------------------------------------------- |
| `FOREBIT_CRYPTO`  | Native coins and tokens via Forebit wallets |
| `CONTRACT_CRYPTO` | ERC-20 tokens via smart contract            |
| `CONTRACT_TRX`    | TRC-20 tokens via smart contract            |
| `NONE`            | No 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.

```javascript theme={null}
// 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:

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

For full event list, payload schemas, and code examples, see the Webhooks guide.

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

Verification reference: [Svix — Verifying Payloads](https://docs.svix.com/receiving/verifying-payloads/how)

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

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

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

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

| Status | Meaning                                    |
| ------ | ------------------------------------------ |
| `400`  | Invalid parameters or validation error     |
| `401`  | Invalid or missing API key                 |
| `403`  | Insufficient permissions for this business |
| `404`  | Payment 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

<CardGroup cols={2}>
  <Card title="Webhooks" icon="bolt" href="/payments/webhooks" />

  <Card title="API Reference" icon="book-open" href="/api-reference/introduction" />

  <Card title="Guide for AI Agents" icon="robot" href="/llms-full">
    Full integration context for Claude, Cursor, and Codex
  </Card>
</CardGroup>