Skip to content
FlowPayDocumentationDocs
Documentation/Overview
THE DEVELOPER GUIDE

Build your
payment flow.

From your first payment link to a complete integration. Everything you need to build with FlowPay, in one place.

EVM testnets, including MonadNode.js 20+Device-key sign-in
Start in the terminal

A few commands. Your first payment request.

CLI quickstartConnect your AI client

Bring payment tools to your agent workspace.

MCP guideBuild it your way

Your interface. FlowPay under the hood.

API reference
YOUR FIRST INTEGRATION

Install. Sign in. Create a payment.

01 — 03
01

Install the CLI

Start with the FlowPay command line. The public package includes the Node.js SDK, so you can move from terminal to code when you are ready.

Terminal
bash
npm install -g --prefer-online https://api.pixuno.xyz/downloads/flowpay-cli-0.1.7.tgz
flowpay --help
Before you start

Use Node.js 20 or later and an EVM settlement wallet. Your wallet address starts with 0x.

02

Make yourself at home

Create an account from your terminal. The CLI wizard collects your business name, recovery email and settlement wallet, then creates a device key and signs you in automatically. There is no password, email code or browser approval.

Registration
bash
flowpay register
FieldWhat you need
Business nameThe name your customers recognize.
Device keyGenerated locally and used automatically for sign-in.
Email addressYour recovery contact. Recording it does not verify ownership.
Settlement walletYour EVM wallet address, starting with 0x.

Already registered?

Sign in automatically using the key on the device where you registered.

Device sign-in
bash
flowpay login

Run flowpay init for first-time setup. Existing browser accounts may use flowpay device. flowpay logout removes the session and keeps your device key for future sign-in.

03

Your first payment request

Request 20 USDC on Ethereum Sepolia. The CLI returns a payment ID, deposit address, and checkout URL to share with your customer.

Create a payment
bash
flowpay request 20 usdc eth
01Create

Choose an amount, asset, and network.

02Share

Send the checkout URL to the payer.

03Confirm

Wait for the verified payment receipt.

A note on networks

The CLI alias eth refers to Ethereum Sepolia testnet. Use monad for Monad Testnet (chain ID 10143) and MON for its native coin. For example: flowpay request 0.01 mon monad. Use the asset and network displayed in the payment request.

Keep the command in your workflow

OptionWhat it does
--no-openCreates the request without opening a browser.
--no-waitReturns the request without waiting for payment.
--jsonReturns structured output for your application.

Use the returned payment ID to pick up monitoring at any time.

Resume monitoring
bash
flowpay payment wait PAYMENT_ID
04

Give your agent payment tools

Create requests, share checkout URLs, and monitor payment state with predictable JSON output. The payer sends the transfer from its wallet.

Agent commands
bash
flowpay request 20 usdc eth --json
flowpay payment status PAYMENT_ID --json
flowpay payment wait PAYMENT_ID --json
One configuration per agent

Set FLOWPAY_CONFIG_DIR to isolate each agent's approved credentials. Keep credentials in configuration, outside prompts and logs.

05

Connect your AI workspace

Use FlowPay from a compatible remote MCP client. Add the hosted connector URL, then authorize the payment tools through your FlowPay account.

MCP server URL
url
https://mcp.pixuno.xyz/mcp
  1. Add the connector

    Paste the server URL into your client's remote MCP settings.

  2. Sign in to FlowPay

    Follow the authorization page and enter your email sign-in code.

  3. Review the permissions

    Approve scoped access through OAuth with PKCE. Manage connected apps in Developers.

Remote connector support and setup vary by client and plan.

06

Your product. Our payment API.

Create payment requests from your backend. Authenticate with your merchant API key and send an idempotency key to prevent duplicate requests.

POST/v1/paymentsCreate a payment
Create with the API
bash
curl https://api.pixuno.xyz/v1/payments \
  -H "Content-Type: application/json" \
  -H "x-flowpay-api-key: $FLOWPAY_API_KEY" \
  -H "Idempotency-Key: order-1042" \
  -d '{
    "amount": "20",
    "asset": "USDC",
    "chain": "ethereum_sepolia",
    "reference": "order-1042"
  }'

The response includes id, address, checkout_url, and status. Share the checkout URL with your customer.

GET/v1/payments/:idRead payment state
Check payment status
bash
curl https://api.pixuno.xyz/v1/payments/PAYMENT_ID \
  -H "x-flowpay-api-key: $FLOWPAY_API_KEY"

Create and store merchant credentials in Developers. API keys belong in your server environment.

07

Let payment events come to you

Register an HTTPS endpoint to receive signed payment lifecycle events. Subscribe to the events your application needs.

Register a webhook
bash
curl https://api.pixuno.xyz/v1/webhooks \
  -H "Content-Type: application/json" \
  -H "x-flowpay-api-key: $FLOWPAY_API_KEY" \
  -d '{
    "url": "https://your-app.com/webhooks/flowpay",
    "events": ["payment.completed", "payment.failed"]
  }'
EventWhen to use it
payment.detectedA transfer has been detected.
payment.confirmedThe payment has reached confirmation.
payment.completedThe payment workflow is complete.
payment.failedThe payment workflow failed.

Verify the signature before handling an event and process repeated deliveries idempotently. Manage endpoints in Webhooks.

CLI reference

Commands, options, and examples.

MCP reference

Remote connectors and local setup.