# 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](/docs/key-concepts/payment-request) 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: ```mermaid 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)](/docs/key-concepts/uai) 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
::::tip **Multi-Asset Flexibility**: By configuring multiple payment options, you allow customers to pay using their preferred cryptocurrency and network, improving conversion rates and user experience. You can later configure a different set of UAIs for your [PoS settlements](/docs/key-concepts/settlements-and-consolidation) ::::: ## 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. ```json 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. ```json 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. ```json 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. ```json { "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](/docs/developers/webhooks) ::::note **Webhook Notification**: You can also poll the Fluxis API to query the status of a payment request. ::::: ```mermaid 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 ` 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" ::::note Don't worry, you can update your PoS configuration at any time. :::::