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 optional
—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 |
Edge cases states are handled by Fluxis using merchant specific configuration.
Recommended integration pattern
- Poll
GET /v1/pos/{posID}/payment-request/{paymentRequestID}or subscribe to account-level webhooks for status changes. - Treat
processingas payment detected; wait forcompleted,underpaid, oroverpaid. confirmedindicates the platform has created the ledger transaction.
Timing and Expiration
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
Code
Response Example
Code
Hosted Checkout Response Example
Code
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
Code
Multi-Asset Support
Merchants configure multiple UAIs on the Point of Sale (config.payment_options). To let payers choose their preferred asset, use the hosted checkout flow:
Code
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.