# Payment Requests

## What are Payment Requests?

**Payment Requests** are payment instructions generated using the Fluxis REST API, signed and converted into NASPIP Tokens. They represent a standardized way for merchants to request payments from users across multiple blockchain networks and assets.

Each Payment Request includes all the essential details a user needs to complete a payment—such as:

- blockchain network
- token
- amount
- address
- order <span style={{ color: '#6c757d' }}>_optional_</span>

—and all of this information is cryptographically signed to ensure authenticity and verification.

## Payment Request States

Payment requests progress through several states during their lifecycle:

### Primary States

| State            | Description                                                          | Duration  |
| ---------------- | -------------------------------------------------------------------- | --------- |
| **`pending`**    | Created via checkout flow; payer has not yet selected a UAI          | Until UAI is selected |
| **`created`**    | Vault address assigned; awaiting on-chain payment                    | 8 minutes |
| **`expired`**    | Payment request timed out without payment                          | Permanent |
| **`processing`** | On-chain deposit detected; awaiting finality                         | Variable  |
| **`completed`**  | Payment received in full (or open-amount payment accepted)           | Permanent |
| **`confirmed`**  | Ledger transaction created after successful payment                  | Permanent |

### Edge Case States

These states handle special scenarios and require coordination between Fluxis and the merchant:

| State           | Description                                          | Handling                       |
| --------------- | ---------------------------------------------------- | ------------------------------ |
| **`underpaid`** | Payment received but amount is less than requested   | Merchant coordination required |
| **`overpaid`**  | Payment received but amount exceeds requested amount | Merchant coordination required |
| **`failed`**    | Unexpected error occurred during processing          | Merchant coordination required |

::::note
Edge cases states are handled by Fluxis using merchant specific configuration.
:::::

### Recommended integration pattern

1. Poll `GET /v1/pos/{posID}/payment-request/{paymentRequestID}` or subscribe to [account-level webhooks](/docs/developers/webhooks) for status changes.
2. Treat `processing` as payment detected; wait for `completed`, `underpaid`, or `overpaid`.
3. `confirmed` indicates the platform has created the ledger transaction.

## Timing and Expiration

::::info
**Timeout Period**: Payment requests expire **8 minutes** after a vault address is assigned (status `created`).

**Grace Period**: Transactions broadcast near expiration may still be detected while the vault remains cached briefly after expiration.
:::::

## Creating a Payment Request

### Basic Request Example

```json
POST /v1/pos/{posID}/payment-request
{
  "reference_id": "order-12345-FLX25",
  "amount": "49.99",
  "unique_asset_id": "npolygon_t0xc2132D05D31c914a87C6611C10748AEb04B58e8F",
  "order": {
    "total": "49.99",
    "coin_code": "USD",
    "description": "Premium Subscription",
    "items": [
      {
        "description": "Premium Subscription",
        "quantity": 1,
        "unit_price": "49.99",
        "amount": "49.99",
        "coin_code": "USD"
      }
    ]
  }
}
```

### Response Example

```json
{
    "status": "success",
    "data": {
        "id": "180ede28-2968-4ac7-8e81-ca446f201949",
        "reference_id": "order-12345-FLX25",
        "status": "created",
        "token": "naspip;fluxis.us;fluxis.qr.dyn.1;v4.public.IhYyMDI...more-token...EwLTAy",
        "expiration": 1759397652
    }
}
```

### Hosted Checkout Response Example

```json
{
  "status": "success",
  "data": {
    "id": "180ede28-2968-4ac7-8e81-ca446f201949",
    "reference_id": "order-12345-FLX25",
    "status": "pending",
    "token": "naspip;fluxis.us;fluxis.qr.dyn.1;v4.public.IhYyMDI...",
    "checkout_url": "https://checkout.fluxis.us/pos/{posID}/payment/{paymentRequestID}",
    "expiration": null
  }
}
```

::::note
Use `POST /v1/pos/{posID}/payment-request` when the payer's UAI is known upfront. Use `POST /v1/pos/{posID}/payment-request-checkout` when the payer should choose from the PoS `payment_options`. Both endpoints require an `online_fixed` Point of Sale.
:::::

## Monitoring Payment Status

Merchants should regularly poll the payment request status to detect successful payments:

### Status Check Example

```json
GET /v1/pos/{posID}/payment-request/{paymentRequestID}

{
  "status": "success",
  "data": {
    "id": "180ede28-2968-4ac7-8e81-ca446f201949",
    "reference_id": "order-12345-FLX25",
    "status": "completed",
    "expiration": 1759397652,
    "amount": "49.99",
    "expected_amount": "49.99",
    "address": "0x1234567890123456789012345678901234567890",
    "unique_asset_id": "npolygon_t0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359",
    "reference_asset_id": "USD",
    "reference_amount": "49.99",
    "exchange_rate": "1",
    "point_of_sale_id": "550e8400-e29b-41d4-a716-446655440000",
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:33:15Z"
  }
}
```

## Multi-Asset Support

Merchants configure multiple [UAIs](/docs/key-concepts/uai) on the **Point of Sale** (`config.payment_options`). To let payers choose their preferred asset, use the hosted checkout flow:

```json
POST /v1/pos/{posID}/payment-request-checkout
{
  "reference_id": "order-12345-FLX25",
  "amount": "49.99",
  "coin_code": "USD",
  "order": {
    "total": "49.99",
    "coin_code": "USD",
    "description": "Premium Subscription"
  }
}
```

The response includes a `checkout_url` and a NASPIP token with the available `payment_options`. The payer selects a UAI at checkout; Fluxis assigns a vault and transitions the payment request from `pending` to `created`.