# Fluxis REST API

The Fluxis REST API lets you authenticate, manage accounts and points of sale, create payment requests, and receive webhook notifications. This page orients you; the interactive reference lives at [/api](/api).

## Base URLs

| Environment | Host                       |
| ----------- | -------------------------- |
| Staging     | `https://api.stgfluxis.us` |
| Production  | `https://api.fluxis.us`    |

All endpoints are prefixed with `/v1`.

## Authentication

Every protected request requires **both** headers:

```
Authorization: Bearer <access_token>
x-fluxis-api-key: <your_api_key>
```

Obtain a token by exchanging your API key and secret:

**`POST /v1/auth/token`**

See [Authentication](/api/authentication#authenticate-and-get-access-token) in the API reference.

::::warning
Never expose your API secret in client-side code, browsers, or mobile apps.
::::

## Core resources

| Resource         | Purpose                                   | Reference                            |
| ---------------- | ----------------------------------------- | ------------------------------------ |
| **Accounts**     | Merchant accounts, settlement addresses   | [/api — Accounts](/api/account)      |
| **Point of Sale**| Payment entry points, payment requests    | [/api — Point of Sale](/api/point-of-sale) |
| **Webhooks**     | Account-level event notifications         | [/api — Webhooks](/api/webhooks)     |
| **Transactions** | Reconciliation and reporting              | [/api — Transactions](/api/transactions) |
| **NASPIP**       | Read or create NASPIP tokens              | [/api — NASPIP Token](/api/naspip-token) |

## Typical integration flow

1. **Authenticate** — `POST /v1/auth/token`
2. **Discover resources** — `GET /v1/account`, `GET /v1/pos?page=1&page_size=20`
3. **Create payments** — `POST /v1/pos/{posID}/payment-request` (or `payment-request-checkout` for hosted checkout)
4. **Receive updates** — Register `POST /v1/account/{accountID}/webhook` with `event_type: payment_request`
5. **Reconcile** — `GET /v1/transactions?page=1&page_size=50` or poll `GET /v1/pos/{posID}/payment-request/{paymentRequestID}`

Step-by-step walkthrough: [API Integration Guide](/docs/developers/tutorials/api-integration-guide).

## Pagination

List endpoints use **`page`** and **`page_size`** query parameters (not offset/limit):

- **POS:** `page` ≥ 1, `page_size` 1–100
- **Transactions:** `page` ≥ 1, `page_size` 5–100
- **Webhook logs:** `page` ≥ 1, `page_size` 5–20

Responses include `{ data, total, page, page_size, total_pages }`.

## Webhooks

Webhooks are registered per **account**, not per POS. Fluxis signs deliveries with HMAC-SHA256.

- [Webhooks overview](/docs/developers/webhooks) — Registration and delivery behavior
- [Webhook Signature Verification](/docs/developers/webhook-signature-verification) — Canonical JSON and test workflow

Supported `event_type` values: `payment_request`, `incoming_transfer`, `refund`.

## Explore the API

<div
  style={{
    padding: "1.5rem",
    border: "1px solid #00e4a4",
    borderRadius: "8px",
    backgroundColor: "rgba(0, 228, 164, 0.05)",
    marginTop: "1.5rem",
  }}
>
  <h4 style={{ marginTop: 0, color: "#00e4a4" }}>Interactive API Reference</h4>
  <p style={{ marginBottom: "1rem" }}>
    Browse endpoints, schemas, and try requests in the playground.
  </p>
  <a href="/api" style={{ color: "#00d086", fontWeight: 600 }}>
    Open API Reference →
  </a>
</div>

## Related guides

- [API Integration Guide](/docs/developers/tutorials/api-integration-guide)
- [Create and Monitor Payment Requests](/docs/developers/tutorials/payment-request)
- [Webhooks](/docs/developers/webhooks)
- [Webhook Signature Verification](/docs/developers/webhook-signature-verification)
- [SDKs (coming soon)](/docs/developers/sdk)