Copy page

Tutorials

API Integration Guide

This guide describes the recommended steps to integrate with the Fluxis API, from credential provisioning to transaction reconciliation.

Integration overview

A typical Fluxis integration follows these steps:

1. Credential provisioning — Create an API key in the dashboard (read + write roles)
2. Authentication — Exchange credentials for a Bearer access token
3. Resource discovery — Retrieve your default accounts and default points of sale (the ones created when you signed up)
4. Create your online POS — Set up your POS for online payments, so it can generate multiple payment requests in parallel
5. Settlement configuration — Configure the crypto address where collected assets will be delivered. You can do this in the dashboard or via the API.
6. Payment request creation — Create a payment request for each checkout attempt
7. Monitor payment status — Webhooks (push) or polling (pull)—pick one or both
8. Reconciliation — Periodically query transactions to catch missed events

Before you start

Environments

Environment	Host
Staging	https://api.stgfluxis.us
Production	https://api.fluxis.us

Required headers

All protected Fluxis endpoints require both headers:

• Authorization: Bearer <access_token>
• x-fluxis-api-key: <your_api_key>

---

Step 1 — Credential provisioning

Before making any API calls, create API credentials in the Fluxis Dashboard.

Create an API key in the dashboard

1. Sign in to the Fluxis Dashboard (staging or production).
2. Open Developers → API Keys (or navigate to /app/api-keys).
3. Click Create (or equivalent) to add a new key.
4. Assign read and write roles so you can list resources and create payment requests.
5. Complete the 2FA challenge when prompted (Two-Factor Authentication must be enrolled first).
6. Copy the API Secret immediately—it is shown once and cannot be retrieved later.

You will receive:

• API Key ID (e.g. fxs.stg.<uuid> for staging, fxs.prd.<uuid> for production)
• API Secret — store in a secrets manager or environment variables

See API Credentials for roles, IP allowlisting, and lifecycle.

---

Step 2 — Authentication

Exchange your credentials for an access token that must be included in all subsequent API requests.

Endpoint: POST /v1/auth/token

See the full request/response format in our API Reference - Authentication.

Token usage

Include the access token in all protected requests:

Code
Authorization: Bearer <access_token>
x-fluxis-api-key: <your_api_key>

Token lifecycle

• Expiration: Access tokens expire (check the expired_at field in the response)
• Renewal: Implement a mechanism to refresh the token before it expires
• Rotation: Rotate your API Key/Secret immediately if you suspect they have been compromised

---

Step 3 — Resource discovery

After authentication, retrieve information about your default accounts and default points of sale, or you can create new ones.

3.1 Retrieve accounts

Accounts represent your merchant's financial accounts within Fluxis.

Endpoint: GET /v1/account

See the full response format in our API Reference - Accounts.

3.2 Retrieve points of sale

Points of Sale (POS) represent your payment entry points — physical or virtual locations where you accept payments. You'll need the POS ID when creating payment requests.

Endpoint: GET /v1/pos?page=1&page_size=20

Required query parameters: page (≥ 1) and page_size (1–100). Organization keys may filter with account_id.

See the full response format in our API Reference — Point of Sale.

---

Step 4 — Settlement configuration

Before accepting payments, you need to configure where collected crypto assets will be delivered.

All assets collected from a specific network (e.g., USDT, USDC, or any other tokens on Polygon) will be delivered to the settlement address configured for that network.

---

Step 5 — Payment request creation

Create a payment request for each customer checkout attempt. The response includes a NASPIP token containing all payment information.

Endpoint: POST /v1/pos/:posID/payment-request

Key fields:

• amount — The payment amount (e.g., "49.99")
• unique_asset_id — The target asset/network (learn about UAIs)
• reference_id — Your internal order ID for reconciliation
• order — Optional structured order data for receipts/UX

See the full request/response format in our API Reference - Payment Request.

5.1 Displaying the NASPIP token

The token returned in the response is a NASPIP token that you present to the customer.

Desktop checkout: Display the NASPIP token as a QR code for users to scan with their wallet app.

Mobile checkout: Display a "Pay with [wallet app name]" button that opens the wallet app via deep link:

Code
[wallet app deeplink url]?<custom_query_params>&naspip_token=<NASPIP_TOKEN>

5.2 Hosted checkout (optional)

For a Fluxis-hosted payment page instead of embedding the NASPIP token yourself:

Endpoint: POST /v1/pos/:posID/payment-request-checkout

The response includes a token and checkout_url — a NASPIP-resolvable URL (same value embedded in the token) for backend-only or wallet-app consumption, not a browser page. For a Fluxis-hosted payment page, use the hosted_checkout_url field instead — a link to the hosted checkout page (https://checkout.fluxis.us/checkout/:id). Redirect the customer's browser there directly; it polls GET /public/checkout/:sessionId (no authentication required — the session ID is the access control, the same model Stripe and MercadoPago use) to render live payment status. When the session completes, the hosted page redirects to return_url: for a generic point of sale that is config.return_url on the POS; for a Tiendanube session it is the per-attempt callback for the terminal outcome (success, failure, or cancel) stored at Process Payment, not the POS return URL.

If the point of sale (or a payment link tied to it) has more than one configured payment option, the hosted checkout page shows an asset picker before a vault is assigned; the shopper's choice is submitted via POST /public/checkout/:sessionId/select-asset.

Payment links reach the same hosted checkout page through their own endpoints, without the merchant backend calling payment-request-checkout at all: GET /public/payment-links/:code/checkout returns the link's public data, and POST to the same path opens a checkout session. Both return a checkout_session object in the shape described above, so the hosted page renders a payment link exactly like a point-of-sale session. These endpoints keep the checkout session in a cookie (credentials: "include" is required), which is what stops a page reload or status poll from creating a duplicate payment request; the shopper's asset choice is submitted with PUT to the same path rather than select-asset.

See API Reference — Create payment request checkout.

---

Step 6 — Choose how to monitor payments

After creating a payment request, you need to know when the customer pays. Pick one or both of the following strategies:

Strategy	Delivery	Best for	Requirements
Webhooks (Option A)	Push — Fluxis POSTs to your server	Production integrations, real-time UX	Public HTTPS endpoint, signature verification
Polling (Option B)	Pull — your server queries Fluxis	Simple backends, local dev, no public URL	Valid Bearer token + API key; poll every ~3 seconds

Option A — Webhook notifications

Webhooks are the recommended way to receive real-time payment status updates.

A.1 Configure your webhook endpoint

First, ensure you have a publicly accessible HTTPS endpoint ready to receive POST requests from Fluxis.

Then register a webhook on the account linked to your POS (use the account_id from your POS or account list):

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

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

Fluxis returns a secret once on create — store it securely for signature verification.

See API Reference — Create webhook.

A.2 Webhook events

Fluxis sends payment_request webhooks when status becomes:

Status	Description	Webhook delivered
processing	Payment detected, awaiting blockchain confirmations	Yes
completed	Payment confirmed — fulfill the order	Yes
underpaid	Customer sent less than the requested amount	Yes
overpaid	Customer sent more than the requested amount	Yes
expired	No payment in time	No — poll instead
failed	Unexpected processing error	No — poll / support

A.3 Handling webhooks

When you receive a webhook notification:

1. Verify authenticity — Validate the HMAC signature over the full parsed body { "data": … } using the secret from create — see Webhook Signature Verification
2. Process the status — Update your internal order status and notify the customer
3. Acknowledge receipt — Return HTTP 200 OK to confirm receipt

A.4 Idempotency

You may receive duplicate webhook events. Ensure your handler is idempotent — processing the same event multiple times should produce the same result.

A.5 Test your handler

After registration, trigger a signed sample delivery:

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

Fluxis POSTs a payment_request_status_update payload using the same signing path as production. Verify the signature in your handler and return HTTP 200. See Webhook Signature Verification for the canonical JSON rules and worked example.

You can also register webhooks from the dashboard under Developers → Webhooks. See Webhooks for API and dashboard options.

---

Option B — Polling

If you do not have a public HTTPS endpoint—or prefer a simpler first integration—poll the payment request status on a fixed interval (for example, every 3 seconds) until the status is terminal.

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

Required headers: Authorization: Bearer <token> and x-fluxis-api-key: <your_api_key>.

Recommended polling pattern

1. After creating a payment request, record paymentRequestID and posID.
2. Poll every ~3 seconds while status is created, pending, confirmed, or processing.
3. Stop polling when status is terminal: completed, expired, underpaid, overpaid, or failed.
4. On completed, fulfill the order; on expired, offer to create a new request.

Example (curl):

Code
curl "https://api.stgfluxis.us/v1/pos/${POS_ID}/payment-request/${PAYMENT_REQUEST_ID}" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "x-fluxis-api-key: ${API_KEY}"

Example (Node.js loop):

Code
const TERMINAL = new Set([
  "completed",
  "expired",
  "underpaid",
  "overpaid",
  "failed",
]);
const POLL_MS = 3000;

async function waitForPayment(posId, paymentRequestId) {
  while (true) {
    const res = await fetch(
      `${API_BASE}/v1/pos/${posId}/payment-request/${paymentRequestId}`,
      {
        headers: {
          Authorization: `Bearer ${accessToken}`,
          "x-fluxis-api-key": apiKey,
        },
      },
    );
    const { data } = await res.json();
    if (TERMINAL.has(data.status)) return data;
    await new Promise((r) => setTimeout(r, POLL_MS));
  }
}

See the full response format in our API Reference — Get payment request.

---

Step 7 — Reconciliation

Even with webhooks or polling at checkout time, run periodic reconciliation to ensure no payments were missed (downtime, network issues, or handler bugs).

Query a specific payment request

If you didn't receive a webhook (or your system was down), fetch the payment request status directly:

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

List transactions for reconciliation

For batch reconciliation, query the transactions endpoint:

Endpoint: GET /v1/transactions?page=1&page_size=50

Required query parameters: page (≥ 1) and page_size (5–100).

Optional filters:

• accountID — Filter by account (organization-level API keys only)

The response is paginated: { data, total, page, page_size, total_pages }.

---

Payment request lifecycle

Payment requests move through the following states:

State	Description	Merchant action
pending	Checkout created, currency not selected	Wait or display hosted checkout
created	Address assigned, awaiting payment	Display QR/link to customer
confirmed	Internal confirmation step	Usually no merchant action
processing	Payment detected, awaiting confirmations	Keep waiting — don't fulfill yet
completed	Payment confirmed	Fulfill the order
expired	No payment received in time	Offer customer to retry (create new request)
underpaid / overpaid / failed	Edge cases	Contact Fluxis support

Learn more: Payment Flows - Happy Path and Payment Flows - Edge Cases.

---

Go-live checklist

Before going to production, verify:

• You can obtain and refresh Bearer tokens via POST /v1/auth/token
• You can list your POS and select the correct posID
• Your checkout creates one payment request per attempt
• You display the NASPIP token correctly (QR code or deep link)
• You have a monitoring strategy: webhooks and/or polling (~3 s interval until terminal status)
• If using webhooks: registered via POST /v1/account/{accountID}/webhook with event_type: payment_request
• Webhook secret stored from create response and used for signature verification
• Test delivery via POST /v1/account/{accountID}/webhook/{webhookID}/test verifies and returns HTTP 200
• Your webhook endpoint is publicly accessible and responds with HTTP 200
• Your webhook handler is idempotent
• If using polling: GET /v1/pos/:posID/payment-request/:paymentRequestID stops on terminal status
• You have a periodic reconciliation process (GET /v1/transactions)

---

Need help?

If you have questions about onboarding, credentials, or production readiness, contact us at [email protected].