Copy page

Key Concepts

Point of Sales

What are Point of Sales?

A Point of Sale (PoS) is a foundational entity in the Fluxis platform that serves as a payment collection endpoint for your organization. Think of it as a digital cash register or payment terminal that enables you to generate and manage payment requests (more details in the Payment Requests section).

Each PoS acts as a distinct payment channel, allowing you to:

• Create payment requests for customers
• Configure accepted payment methods (cryptocurrencies and blockchain networks)
• Track and monitor incoming payments
• Organize transactions by location, department, or business unit

Key Concepts

Point of Sale Types

Type	Use case	Payment flow
online_fixed	E-commerce, app integrations	Create payment requests via POST /v1/pos/{posID}/payment-request or hosted checkout via POST /v1/pos/{posID}/payment-request-checkout
cashier_fixed	Physical register with merchant-set amount	Merchant creates a payment intention; customer scans QR
cashier_open	Customer-entered amount (e.g. donation/tip jar)	Customer scans QR and enters amount at checkout

Organization and Account Structure

PoS belong to an Organization (your business entity) and can optionally be associated with a specific Account for more granular organization:

Code
graph TD
    A[Organization] --> B[PoS #1]
    A --> C[PoS #2]
    A --> D[Account]
    D --> E[PoS #3]
    D --> F[PoS #4]

This hierarchical structure allows you to:

• Separate payment channels by department, location, or purpose
• Maintain distinct payment configurations for different use cases
• Track and report on payments at multiple levels

Payment Options Configuration

Each PoS can be configured with specific payment options, which are Unique Asset IDs (UAIs) representing the cryptocurrencies and networks you accept:

Network	Token	Example UAI
Polygon	USDC	npolygon_t0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359
Polygon	USDT	npolygon_t0xc2132D05D31c914a87C6611C10748AEb04B58e8F
Ethereum	USDC	nerc20_t0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48
Arbitrum	USDC	narbitrum_t0xaf88d065e77c8cC2239327C5EDb3A432268e5831

Point of Sale Properties

Property	Type	Description	Required
id	UUID	Unique identifier for the Point of Sale	Auto-generated
name	string	Human-readable name for identification	Yes
type	string	PoS mode: online_fixed, cashier_fixed, or cashier_open	Yes
organization_id	UUID	Parent organization identifier	Auto-generated
account_id	UUID	Account that owns this PoS (required when creating as an organization)	Yes
config	object	Configuration object (see below)	No
created_at	timestamp	Creation timestamp	Auto-generated
updated_at	timestamp	Last modification timestamp	Auto-generated

Config object (config)

Property	Type	Description
payment_options	string[]	Accepted UAIs; defaults to a platform preset if omitted
reference_currency	string	Reference currency for amounts (USD or ARS)
merchant	object	Merchant name and description shown to payers

Common Use Cases

1. E-commerce Checkout

Create a PoS for your online store to process customer payments at checkout.

Code
POST /v1/pos
{
  "name": "Main Store Checkout",
  "type": "online_fixed",
  "account_id": "550e8400-e29b-41d4-a716-446655440000",
  "reference_currency": "USD",
  "payment_options": [
    "npolygon_t0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359",
    "npolygon_t0xc2132D05D31c914a87C6611C10748AEb04B58e8F"
  ]
}

2. Physical Location

Set up distinct PoS for each physical location or retail outlet.

Code
POST /v1/pos
{
  "name": "Manhattan Store - 5th Avenue",
  "type": "cashier_fixed",
  "account_id": "550e8400-e29b-41d4-a716-446655440000",
  "reference_currency": "USD",
  "payment_options": ["npolygon_t0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359"]
}

3. Subscription Services

Dedicated PoS for recurring subscription payments.

Code
POST /v1/pos
{
  "name": "Premium Subscriptions",
  "type": "online_fixed",
  "account_id": "550e8400-e29b-41d4-a716-446655440000",
  "reference_currency": "USD",
  "payment_options": [
    "npolygon_t0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359",
    "nerc20_t0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"
  ]
}

4. Department-Specific

Organize payments by department using the account structure.

Code
{
  "name": "Marketing Department Events",
  "type": "online_fixed",
  "account_id": "550e8400-e29b-41d4-a716-446655440000",
  "reference_currency": "USD",
  "payment_options": ["npolygon_t0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359"]
}

Workflow

Once a PoS is created, it becomes the foundation for accepting payments:

1. Create PoS → Configure your payment endpoint with accepted assets
2. Generate Payment Request → Create individual payment requests linked to this PoS
3. Customer Payment → Customer pays using any of the configured payment options
4. Payment Confirmation → Fluxis detects and confirms the payment on-chain
5. Webhook Notification → Your system receives real-time payment status updates via account-level webhooks

Code
sequenceDiagram
    participant M as Merchant
    participant F as Fluxis API
    participant B as Blockchain
    participant C as Customer

    M->>F: Create PoS
    F-->>M: PoS ID
    M->>F: Create Payment Request (via PoS)
    F-->>M: Payment Request + NASPIP Token
    M->>C: Display Payment Request
    C->>B: Send Payment
    B->>F: Payment Detected
    F->>M: Webhook: Payment Confirmed

API Endpoints

All endpoints require Authorization: Bearer <token> and x-fluxis-api-key headers.

Method	Endpoint	Description
GET	/v1/pos?page=1&page_size=20	List PoS (requires page and page_size)
POST	/v1/pos	Create PoS
GET	/v1/pos/{posID}	Get PoS by ID
PUT	/v1/pos/{posID}	Update PoS name and config
DELETE	/v1/pos/{posID}	Delete PoS
POST	/v1/pos/{posID}/payment-request	Create fixed-asset payment request (online_fixed only)
POST	/v1/pos/{posID}/payment-request-checkout	Create multi-asset hosted checkout (online_fixed only)
GET	/v1/pos/{posID}/payment-request/{paymentRequestID}	Get payment request status
GET	/v1/pos/{posID}/qr	Get static QR NASPIP token (cashier_* types)
POST	/v1/pos/{posID}/payment-intention	Create cashier payment intention
GET	/v1/pos/{posID}/payment-intention	Get active payment intention
POST	/v1/pos/{posID}/payment-intention/close	Close active payment intention

Best Practices

Naming Convention

Use clear, descriptive names that reflect the purpose or location:

• ✅ "Downtown Store - Main Register"
• ✅ "Website Checkout - Production"
• ✅ "Mobile App - In-App Purchases"
• ❌ "PoS 1"
• ❌ "Test123"