# Use Cases

This document explores real-world applications and use cases for implementing secure payments with Fluxis API and the NASPIP protocol, demonstrating how to integrate blockchain payments into your applications using the supported merchant API flow.

::::tip Authentication pattern
All examples below assume you have already exchanged your API key and secret for a Bearer token via `POST /v1/auth/token`. Protected routes require **both** `Authorization: Bearer <token>` and `x-fluxis-api-key: <api_key>`. Never expose API secrets in client-side code.
::::

## E-commerce and Retail

### Online Store Payments

**Scenario**: An e-commerce platform wants to accept cryptocurrency payments alongside traditional payment methods.

**Fluxis API Solution**:

```javascript
const API_BASE = "https://api.fluxis.us/v1";
const POS_ID = "YOUR_POINT_OF_SALE_ID";

// 1) Exchange API key + secret for an access token (server-side only)
const authRes = await fetch(`${API_BASE}/auth/token`, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    api_key: process.env.FLUXIS_API_KEY,
    api_secret: process.env.FLUXIS_API_SECRET,
  }),
});
const { data: auth } = await authRes.json();

// 2) Create a payment request for a checkout
const prRes = await fetch(`${API_BASE}/pos/${POS_ID}/payment-request`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${auth.token}`,
    "x-fluxis-api-key": process.env.FLUXIS_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    amount: "299.99",
    unique_asset_id: "npolygon_t0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359",
    reference_id: "order-12345",
  }),
});
const { data: paymentRequest } = await prRes.json();

// 3) Present paymentRequest.token to the payer (QR / deep link / hosted checkout)
// Optional: POST /pos/:posID/payment-request-checkout for a hosted checkout URL
```

**Benefits**:

- **🚀 Rapid Integration**: Get started in minutes with Fluxis API
- **🔐 Enterprise Security**: Signed NASPIP (PASETO v4) payment instructions and webhook signature verification
- **🌐 Multi-Network**: Support for configured EVM assets (UAIs) on enabled networks such as Polygon, Base, Avalanche, and Arbitrum
- **📱 Flexible checkout**: NASPIP token QR, deep links, or hosted checkout
- **⚡ High Performance**: Scalable infrastructure for production applications

### Point-of-Sale (POS) Systems

**Scenario**: A retail store wants to accept cryptocurrency payments at physical locations using a cashier-style flow.

**Fluxis API Implementation**:

```javascript
const API_BASE = "https://api.fluxis.us/v1";

class POSSystem {
  constructor(apiKey, apiSecret, posId) {
    this.apiKey = apiKey;
    this.apiSecret = apiSecret;
    this.posId = posId;
    this.accessToken = null;
  }

  async authenticate() {
    const res = await fetch(`${API_BASE}/auth/token`, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        api_key: this.apiKey,
        api_secret: this.apiSecret,
      }),
    });
    const { data } = await res.json();
    this.accessToken = data.token;
  }

  authHeaders() {
    return {
      Authorization: `Bearer ${this.accessToken}`,
      "x-fluxis-api-key": this.apiKey,
      "Content-Type": "application/json",
    };
  }

  async createPaymentIntention(amount, coinCode = "USD") {
    const res = await fetch(
      `${API_BASE}/pos/${this.posId}/payment-intention`,
      {
        method: "POST",
        headers: this.authHeaders(),
        body: JSON.stringify({
          amount,
          coin_code: coinCode,
          external_id: `pos-${Date.now()}`,
        }),
      },
    );
    return (await res.json()).data;
  }

  async getPaymentRequest(paymentRequestId) {
    const res = await fetch(
      `${API_BASE}/pos/${this.posId}/payment-request/${paymentRequestId}`,
      { headers: this.authHeaders() },
    );
    return (await res.json()).data;
  }
}

// Usage
const pos = new POSSystem(
  process.env.FLUXIS_API_KEY,
  process.env.FLUXIS_API_SECRET,
  "YOUR_POS_ID",
);
await pos.authenticate();
const intention = await pos.createPaymentIntention(50.0, "USD");
// Display intention token as QR; poll or use webhooks for status updates
```

## Financial Services

### Cross-Border Remittances

**Scenario**: A remittance service wants to offer fast, low-cost international money transfers using stablecoins.

**Fluxis API Implementation**:

```javascript
async function createRemittancePayment({ amount, referenceId, posId }) {
  const auth = await getAccessToken(); // POST /v1/auth/token

  const res = await fetch(
    `https://api.fluxis.us/v1/pos/${posId}/payment-request`,
    {
      method: "POST",
      headers: {
        Authorization: `Bearer ${auth.token}`,
        "x-fluxis-api-key": process.env.FLUXIS_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        amount: amount.toString(),
        unique_asset_id: "npolygon_t0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359",
        reference_id: referenceId,
        order: {
          description: "Cross-border remittance",
        },
      }),
    },
  );

  const { data } = await res.json();
  return {
    paymentRequestId: data.id,
    naspipToken: data.token,
    expiration: data.expiration,
  };
}
```

Register an account webhook to receive `completed`, `underpaid`, or `overpaid` status updates and fulfill the transfer once payment is confirmed.

### DeFi Payment Integration

**Scenario**: A DeFi protocol wants to integrate secure payment instructions for yield farming and liquidity provision.

```javascript
async function createPoolDepositPayment({ poolAddress, amount, posId }) {
  const auth = await getAccessToken();

  const res = await fetch(
    `https://api.fluxis.us/v1/pos/${posId}/payment-request`,
    {
      method: "POST",
      headers: {
        Authorization: `Bearer ${auth.token}`,
        "x-fluxis-api-key": process.env.FLUXIS_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        amount: amount.toString(),
        unique_asset_id: "npolygon_t0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359",
        reference_id: `pool-${poolAddress.slice(0, 8)}`,
        order: {
          description: `Yield farming deposit — ${poolAddress}`,
        },
      }),
    },
  );

  const { data } = await res.json();
  return { paymentRequest: data, naspipToken: data.token };
}
```

## Gaming and Entertainment

### In-Game Purchases

**Scenario**: A mobile game wants to accept cryptocurrency payments for in-game items and premium features.

```javascript
async function createInGamePurchase({ itemId, price, playerId, posId }) {
  const auth = await getAccessToken();

  const res = await fetch(
    `https://api.fluxis.us/v1/pos/${posId}/payment-request`,
    {
      method: "POST",
      headers: {
        Authorization: `Bearer ${auth.token}`,
        "x-fluxis-api-key": process.env.FLUXIS_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        amount: price.toString(),
        unique_asset_id: "npolygon_t0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359",
        reference_id: `player-${playerId}-item-${itemId}`,
        order: {
          description: `In-game purchase: ${itemId}`,
        },
      }),
    },
  );

  const { data } = await res.json();

  // Optional: hosted checkout instead of raw NASPIP token
  // POST /v1/pos/:posID/payment-request-checkout

  return {
    paymentRequestId: data.id,
    naspipToken: data.token,
    referenceId: data.reference_id,
  };
}

// On webhook `completed` (or poll GET /pos/:posID/payment-request/:id):
// grant the item to the player matched by reference_id
```

## Why Choose Fluxis API for These Use Cases?

### 🚀 Rapid Development

- **5 minutes to first payment**: Get started immediately
- **Simple REST API**: Easy integration with any technology stack
- **Comprehensive documentation**: Clear examples and guides

### 🔒 Enterprise Security

- **Signed payment instructions**: NASPIP tokens with verifiable payloads
- **Webhook authenticity**: HMAC-SHA256 signatures on outbound events
- **Server-side credentials**: API secrets never belong in client apps

### 📈 Production Ready

- **Production infrastructure**: Designed for high availability (confirm SLA terms with Fluxis sales)
- **Global CDN**: Fast response times worldwide
- **Auto-scaling**: Handles traffic spikes automatically

### 🛠️ Developer Experience

- **Interactive API playground**: Test endpoints directly in the browser
- **Integration guides**: Step-by-step merchant onboarding
- **Expert support**: Contact [support@fluxis.us](mailto:support@fluxis.us) when you need help

## Getting Started

Ready to implement any of these use cases? Start with the [API Integration Guide](/docs/developers/tutorials/api-integration-guide) or explore our [API Reference](/api).

### Next Steps

1. **[Sign up for Fluxis](https://fluxis.us/signup)** - Create your account
2. **[Get your API key](https://fluxis.us/dashboard)** - Generate your first key
3. **[Follow the API Integration Guide](/docs/developers/tutorials/api-integration-guide)** - Make your first API call
4. **[Getting Started](/docs/introduction/getting-started)** - 6-step quick start

---

**Ready to transform your payment experience?** [Start integrating with Fluxis API](https://fluxis.us/signup) today!