# API reference

> Use Revfaro's server-side API to record payments, goals and bot traffic with your website's API key, and find the full interactive reference at /api/docs.

**In short:** The server-side API has three endpoints, all authenticated with your website's API key as a Bearer token. `POST /api/v1/payments` records payments and refunds, `POST /api/v1/goals` records goals for a visitor, and `POST /api/v1/bots` records bot traffic. The interactive reference at /api/docs documents every field and lets you try requests in the browser.

The complete, interactive reference is at **[/api/docs](https://revfaro.com/api/docs)**: every endpoint, field and response, with a form to send test requests.

## Authentication

Each website has its own API key. It starts with `rf_` and is sent as a Bearer token:

```bash
curl https://revfaro.com/api/v1/goals \
  -H "Authorization: Bearer rf_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"visitor_id":"<rf_vid cookie>","name":"signup"}'
```

- Find the key in **Website settings › Setup › Connect payments › Other / API** (also shown in the **Bots** tab). Workspace owners, admins and website managers can see it.
- Keep it on your server, for example in an environment variable such as `REVFARO_API_KEY`. Never put it in browser code or in a public repository.
- The server-side API is for server-to-server calls only: it sends no CORS headers, so browsers can't call it.
- **Rotate** in the **Other / API** tab replaces it; the old key stops working immediately.

## Endpoints

| Endpoint                | What it does                                                                                               | Needs in your plan                 |
| ----------------------- | ---------------------------------------------------------------------------------------------------------- | ---------------------------------- |
| `POST /api/v1/payments` | Records a payment, renewal or refund from any provider. See [Payments API](https://revfaro.com/docs/payments-api/).           | API access and revenue attribution |
| `POST /api/v1/goals`    | Records a goal on a visitor's latest visit. See [Track goals](https://revfaro.com/docs/goals/#track-a-goal-from-your-server). | API access                         |
| `POST /api/v1/bots`     | Records bot traffic, one hit or up to 100. See [Bot traffic](https://revfaro.com/docs/bot-traffic/).                          | An active plan                     |

## Responses and errors

Requests and responses are JSON. Errors always look like this:

```json
{ "error": "Human readable message", "code": "machine_code" }
```

| Status | Meaning                                                                                                                      |
| ------ | ---------------------------------------------------------------------------------------------------------------------------- |
| `200`  | Recorded.                                                                                                                    |
| `400`  | The request body is invalid; the message says which field.                                                                   |
| `401`  | The API key is missing or wrong.                                                                                             |
| `402`  | The workspace's trial or subscription has ended.                                                                             |
| `403`  | The feature isn't part of the workspace's plan.                                                                              |
| `404`  | Goals API only: Revfaro has never seen this visitor.                                                                         |
| `429`  | Gateway request limit, or more than 1,200 Bots API requests a minute for the website. Wait for the seconds in `Retry-After`. |

## Webhook endpoints

Payment providers call these addresses; you only paste them into the provider's dashboard. Each website has its own:

| Provider      | Address                                          |
| ------------- | ------------------------------------------------ |
| Stripe        | `https://revfaro.com/api/webhooks/stripe/YOUR_SITE_ID`       |
| Dodo Payments | `https://revfaro.com/api/webhooks/dodo/YOUR_SITE_ID`         |
| Lemon Squeezy | `https://revfaro.com/api/webhooks/lemonsqueezy/YOUR_SITE_ID` |
| Polar         | `https://revfaro.com/api/webhooks/polar/YOUR_SITE_ID`        |

Requests are verified with the signing secret you saved in **Connect payments**. See the guide for [Stripe](https://revfaro.com/docs/stripe/), [Dodo Payments](https://revfaro.com/docs/dodo-payments/), [Lemon Squeezy](https://revfaro.com/docs/lemon-squeezy/) or [Polar](https://revfaro.com/docs/polar/).

## The tracking endpoint

The browser script sends events to `POST /api/event`. You don't need to call it yourself; it's documented in the reference for completeness. To send it through your own domain, see [Proxy the script](https://revfaro.com/docs/proxy/).

## Frequently asked questions

### Where do I find my Revfaro API key?

In **Website settings › Setup › Connect payments › Other / API**, and in the **Bots** tab. Workspace owners, admins and website managers can see it. Each website has its own key.

### Can I read my statistics with the API?

Not with an API key. The API key is for sending data (payments, goals and bot traffic) from your server.

### What happens when I rotate the API key?

The old key stops working immediately. Update every server that sends payments, goals or bot hits with the new key.

---

Source: https://revfaro.com/docs/api/ · Last updated 2026-10-29