Copy page

Tutorials

Create and Monitor Payment Requests

The Payment Flow

Understanding the complete payment flow helps you integrate Fluxis effectively into your application:

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

    M->>F: Create Payment Request
    F-->>M: Payment Details + NASPIP Token
    M->>C: Display Payment (QR/Link)
    C->>B: Send Payment
    B->>F: Transaction Detected
    F->>M: Webhook: Processing
    B->>F: Transaction Confirmed
    F->>M: Webhook: Completed
    M->>C: Order Confirmed

Flow Breakdown

1. Your app creates a payment request via Fluxis API for a specific amount
2. Fluxis returns payment request details including a NASPIP token
3. Customer sees payment request as a QR code or payment link
4. Customer pays using their crypto wallet
5. Fluxis detects payment on the blockchain and notifies you
6. Transaction confirms and you fulfill the order

Creating a Payment Request

To create a payment request, you'll need:

You can create your first payment request in our API Playground - Payment Request.

Alternatively, use hosted checkout (POST /v1/pos/{posID}/payment-request-checkout) to receive a checkout_url you can redirect customers to without building your own NASPIP UI.

The NASPIP Token

The NASPIP token is a cryptographically signed string that contains all the payment instructions:

Code
naspip;fluxis.us;fluxis.qr.dyn.1;v4.public.IhYyMDI1LTEwLTI...

This token can be:

• Encoded as a QR code for mobile wallet scanning
• Shared as a payment link for web/desktop wallets
• Shared by NFC enabled wallets to perform proximity or offline payment

URL-based NASPIP tokens

Some tokens embed a url instead of inline payment instructions. Use POST /v1/naspip/read with the token — when the payload contains a URL without payment_options, Fluxis resolves payment instructions by fetching that URL server-side before returning the decoded data.

Payment Request States

Payment requests progress through different states during their lifecycle:

State Transition Diagram

Code
stateDiagram-v2
    [*] --> created: Payment Request Created
    created --> expired: 8 minutes timeout
    created --> processing: Payment Detected
    processing --> completed: Correct Amount
    processing --> underpaid: Amount < Expected
    processing --> overpaid: Amount > Expected
    processing --> failed: Error Occurred

    completed --> [*]
    expired --> [*]
    underpaid --> [*]
    overpaid --> [*]
    failed --> [*]

State Descriptions

State	Meaning	What to Do
created	Awaiting payment (active for ~8 minutes)	Display to customer, monitor for changes
processing	Payment detected, awaiting blockchain confirmation	Continue monitoring, inform customer
completed	Payment received and confirmed	Fulfill order, close payment request
expired	Timeout reached without payment	Offer to create new payment request
underpaid	Received less than expected amount	Contact support for resolution
overpaid	Received more than expected amount	Contact support for resolution
failed	Unexpected error during processing	Contact support, may need to create new request

Monitoring Payment Status

After creating a payment request, you need to monitor its status to know when payment is received. There are two approaches:

Option 1: Polling

Periodically check the payment request status by calling the status endpoint.

Endpoint: GET /v1/pos/{posID}/payment-request/{paymentRequestID}

Try it in our API Playground - Get Payment Request.

Polling Strategy

Pros:

• Simple to implement
• Works with any infrastructure
• No additional setup required

Cons:

• Not real-time
• Creates API overhead
• May miss rapid state changes

Option 2: Webhooks

Configure account-level webhooks to receive notifications when payment status changes. This is the recommended approach for production systems.

Endpoint: POST /v1/account/{accountID}/webhook

Try it in the API Playground — Create webhook.

Webhook Setup

Register a full HTTPS URL and set event_type to payment_request:

Code
{
  "url": "https://your-server.com/webhooks/fluxis",
  "event_type": "payment_request"
}

Fluxis generates the signing secret and returns it once in the create response. Webhooks fire for processing, completed, underpaid, and overpaid — not for expired or failed.

See Webhooks guide and Webhook Signature Verification. After registration, validate your handler with POST /v1/account/{accountID}/webhook/{webhookID}/test.

Pros:

• Real-time notifications
• No polling overhead
• Efficient and scalable
• Event-driven architecture

Cons:

• Requires public endpoint
• Need to implement webhook handler
• Should verify webhook signatures

::::tip Best Practice Use webhooks for production and polling as a fallback. Implement both methods to ensure you never miss a payment confirmation. ::::

Handling Different Scenarios

Scenario 1: Successful Payment

1. Customer scans QR code or clicks payment link
2. Customer confirms payment in their wallet
3. Payment appears on blockchain
4. Status changes to processing
5. Transaction receives sufficient confirmations
6. Status changes to completed
7. You fulfill the order

Your action: Fulfill the order when status is completed.

Scenario 2: Expired Payment Request

1. ~8 minutes pass without payment
2. Status changes to expired
3. Payment request is no longer valid

Your action: Offer customer option to create a new payment request.

Scenario 3: Slow Transaction

1. Customer initiates payment near expiration
2. Transaction broadcasts but isn't confirmed before timeout
3. Fluxis grace period processes the late transaction
4. Status updates to processing then completed

Your action: Continue monitoring even after expiration for 2-3 additional minutes.

Best Practices

1. Always Use Reference IDs

2. Display Clear Payment Information

3. Handle Expiration Gracefully

4. Never Trust Status Alone

5. Store Payment Request Data

Common Integration Patterns

E-commerce Checkout Flow

Code
sequenceDiagram
    participant C as Customer
    participant S as Your Store
    participant F as Fluxis

    C->>S: Place Order
    S->>S: Create Order Record
    S->>F: Create Payment Request
    F-->>S: Payment Details
    S->>C: Show Payment QR

    loop Monitor
        C->>F: Send Payment
        F-->>S: Webhook: Processing
        S->>C: Update UI: Processing
        F-->>S: Webhook: Completed
        S->>C: Update UI: Confirmed
    end

    S->>S: Fulfill Order
    S->>C: Send Confirmation Email

Point of Sale Terminal

Code
sequenceDiagram
    participant C as Customer
    participant T as Terminal
    participant F as Fluxis

    T->>T: Cashier Enters Amount
    T->>F: Create Payment Request
    F-->>T: Display QR Code
    C->>F: Customer Scans & Pays

    loop Poll
        T->>F: Check Status
        F-->>T: Status: Processing
        T->>T: Show "Processing"
    end

    F-->>T: Status: Completed
    T->>T: Print Receipt
    T->>C: Transaction Complete

Troubleshooting

Payment Request Not Creating

Symptoms: Error when creating payment request

Common causes:

• Invalid or expired access token
• Point of Sale ID doesn't exist or doesn't belong to your organization
• Invalid UAI format
• Amount is zero or negative

Solution: Verify your authentication token, Point of Sale ID, and request parameters.

Status Not Updating

Symptoms: Status stuck on created despite customer payment

Common causes:

• Payment sent to wrong address
• Payment sent with wrong asset/network
• Insufficient network confirmations
• Customer payment pending in wallet

Solution: Ask customer to verify transaction hash. Check blockchain explorer to confirm transaction status.

Webhooks Not Received

Symptoms: No webhook notifications arriving

Common causes:

• Webhook URL not publicly accessible
• Firewall blocking Fluxis IP addresses
• Webhook endpoint returning errors
• SSL/TLS certificate issues

Solution: Call POST /v1/account/{accountID}/webhook/{webhookID}/test for a signed sample delivery. Check server logs, verify SSL, and confirm signature verification passes before processing events.

Testing Your Integration

Before going live, thoroughly test your integration:

Test Checklist

• Create payment request with valid parameters
• Display NASPIP token as QR code
• Monitor status changes via polling
• Handle completed status correctly
• Handle expired status gracefully
• Test webhook delivery and parsing
• Verify webhook signature using secret from create response
• Test webhook via POST /v1/account/{accountID}/webhook/{webhookID}/test
• Handle network errors and retries
• Test edge cases (underpaid, overpaid)
• Verify amount precision (decimals)