---
name: inflow-payments
description: "Integrate InFlow stablecoin payments into any project. Use this skill when the user wants to: accept payments, add a checkout, request a payment, build a payment flow, integrate InFlow, accept USDC/USDT/EURC/PYUSD, set up consumer login via InFlow, register users with InFlow, handle payment webhooks, create spending policies for autonomous agents, build a 0-click headless payment flow, or add InFlow checkout to a marketplace app (note: native multi-recipient splits are not supported by the InFlow API). Also trigger on: 'add inflow', 'inflow payment', 'inflow checkout', 'stablecoin payment', 'crypto payment', 'accept stablecoins', 'pay with usdc', 'inflow webhook', 'inflow login', 'inflow policy'."
---
# InFlow Payments Integration
InFlow is a stablecoin payment platform. Sellers (merchants, agents) request payments from consumers; consumers approve via mobile/email/SMS; settlements happen on-chain. Consumers can pre-configure **policies** that auto-approve requests within budget — enabling 0-click flows for autonomous agents.
This skill integrates InFlow into any project — backend service, full-stack web app, CLI, autonomous agent, or worker — without forcing a specific framework or language. **Important:** the integration itself is always backend work. Browser code is only ever the optional `inflow.js` popup (UX only); every REST call to InFlow and the `INFLOW_API_KEY` live exclusively on the server. See the Hard Backend Gate section for the rule and how to handle projects without a backend yet.
## What InFlow Supports
| Capability | Endpoint(s) | Use case |
|---|---|---|
| **User search** | `POST /v1/users/search` | Find a consumer by email, mobile, or username |
| **User registration** | `POST /v1/requests/register` | Onboard a new consumer (out-of-band approval) |
| **Login** | `POST /v1/requests/login` | Authenticate a consumer (out-of-band approval) |
| **Payment** | `POST /v1/requests/payment` | Request a stablecoin payment from a consumer |
| **Policies** | `POST /v1/policies`, `POST /v1/requests/policy` | Pre-approved spending rules for headless / 0-click flows |
| **Webhooks** | Inbound `POST` to your endpoint | Receive transaction/approval status changes |
| **Polling fallback** | `GET /v1/requests/{requestId}` | Check status without webhooks |
| **Wallet read** | `GET /v1/balances`, `GET /v1/transactions` | Read balances and transaction history |
| **Crypto wallets** | `GET/POST /v1/deposit-addresses`, `/v1/withdrawal-addresses` | Manage on-chain wallet addresses |
| **Agentic users** | `POST /v1/users/agentic` | Create a programmatic account, get an API key |
**Currencies:** `USDC`, `USDT`, `EURC`, `PYUSD` (stablecoins only — no fiat)
**Blockchains:** `APTOS`, `BASE`, `SOLANA`, `WORLD`
## What This Skill Does NOT Do
These features are **not exposed by the InFlow public API**. If the user asks for any of them, stop and tell them they're not supported — do not attempt workarounds:
- **Marketplace splits** — No `splits[]` field on `PaymentRequest`. Multi-recipient payments would need separate sequential requests with no atomic guarantee.
- **Refund creation** — Transactions can have status `REFUNDED`, but there's no API to initiate one. Refunds are dashboard-only or out-of-band.
- **Webhook URL registration via API** — Webhook URLs are configured via the InFlow dashboard. There's no `POST /v1/webhooks` to register them programmatically.
- **OAuth flow for sellers** — Despite some legacy documentation referencing "OAuth", consumer authentication is entirely SDK-mediated. There's no OAuth dance for the integrating seller.
---
## Defaults & Decision Tree
When the user doesn't specify, use these defaults:
| Question | Default | Why |
|---|---|---|
| Currency | `USDC` | Most widely-held stablecoin |
| `userDetails` field | `["EMAIL"]` | Required field; email is the minimum useful identifier |
| Display mode | See decision below | Depends on whether a browser is involved |
| Production vs sandbox | Sandbox SDK URL until user confirms | Production SDK URL is not yet documented |
**Display mode:** `FULL` if the consumer is interacting with a browser at the moment of payment (and the page can load `inflow.js`). `HEADLESS` for everything else: server-to-server, autonomous agents, scheduled jobs, AI workers.
**Webhook vs polling:** Webhooks for production. Polling only for local development, scripts, or anything without a public HTTPS endpoint.
**User identification:** A payment must be addressed to a known `userId`. The agent must either:
- Get the `userId` from the user (if they already know it), OR
- Search by email/mobile/username via `POST /v1/users/search`, OR
- Register a new consumer if the search returns 404
Always do user identification BEFORE creating a payment request.
---
## 🛑 Hard Backend Gate (Read Before ANY Code)
InFlow integration is **always backend work**. The `INFLOW_API_KEY` is a merchant key that must never reach a browser. There is no exception, demo mode, or "just for now" carve-out.
### Mandatory gate
Before writing any InFlow HTTP call, you MUST be able to **name the single server-only surface** where `X-API-Key` will be set. Acceptable surfaces:
- An Express / Fastify / Koa / Hono / Hapi route handler
- A Next.js Route Handler (`app/api/.../route.ts`) or Server Action — NOT a Client Component
- A SvelteKit `+server.ts` / `+page.server.ts` — NOT a `+page.svelte` component
- A Nuxt `server/api/*.ts` / `server/routes/*.ts` — NOT a Vue component or composable
- A Remix `loader` / `action` — NOT a route component body
- A serverless function: Vercel Function, Netlify Function, Cloudflare Worker, AWS Lambda, etc.
- A Python / Go / Rust / .NET / Java HTTP service
- A standalone backend script or worker (no browser involved)
If the project does NOT have any such surface — for example, a pure Vite + React SPA, a static site, a Storybook setup, a Chrome extension popup — **STOP**. Tell the user they need a backend surface for the API key, even if it's a single-file serverless function or a 30-line Express server. Offer to scaffold one. Do not proceed until the user agrees and the backend surface exists.
### Framework-specific footguns (key-leak mechanics)
These are real, common ways merchant keys end up in browsers. Refuse them all.
**Next.js:**
- `process.env.INFLOW_API_KEY` referenced inside a `'use client'` component is `undefined` at runtime — Next.js does NOT bundle non-`NEXT_PUBLIC_` env vars into client code. The bug surfaces as a broken request with no auth header.
- The disaster happens when an agent "fixes" this `undefined` by renaming the var to `NEXT_PUBLIC_INFLOW_API_KEY`. That prefix tells the bundler to inline the value into the client bundle → **the key is now shipped to every visitor**.
- **NEVER prefix `INFLOW_API_KEY` with `NEXT_PUBLIC_`.** The correct fix is to move the call to a Server Component, Route Handler (`app/api/.../route.ts`), or Server Action — never to make the key public.
**Vite (React, Vue, Svelte, Solid, etc.):**
- `import.meta.env.INFLOW_API_KEY` is `undefined` unless prefixed with `VITE_`. Some agents "fix" this by renaming to `VITE_INFLOW_API_KEY` → **Vite then inlines the key into the client bundle and ships it to every visitor**.
- **NEVER prefix `INFLOW_API_KEY` with `VITE_`.** Vite has no server runtime by itself. If you need a backend, the user has to add one (Express, Fastify, or pair with a serverless function).
**SvelteKit:**
- Components and `+page.svelte` files run in the browser. Use `+server.ts`, `+page.server.ts`, or `$lib/server/*` (the `server` directory is enforced as server-only by the bundler).
**Nuxt:**
- Vue components and composables run in the browser. Use `server/api/*` route handlers or `server/utils/*`. Never read `INFLOW_API_KEY` from a `
```
> ⚠️ This is the **sandbox** URL. The production URL is not yet publicly documented. Before deploying to production, the user should confirm the production SDK URL with InFlow.
**Render a request:**
```js
// Get the requestId from your backend (which calls POST /v1/requests/{login|register|payment|...})
const requestId = await fetchRequestIdFromYourBackend();
const request = new InFlow.Request(requestId);
request.render({
statusCallback: (status) => {
// status.status is one of: PENDING, APPROVED, DECLINED, EXPIRED, CANCELLED
if (status.status === InFlow.STATUS.APPROVED) {
// SDK indicated user approved. Show "processing..."
// DO NOT fulfill the order here — wait for the webhook.
}
}
});
```
Same pattern works for login, register, payment, and details requests. Only the backend endpoint that produces the `requestId` differs.
**Adapt the surrounding markup to the user's framework** — wrap in a React/Vue/Svelte component if needed. The SDK itself is framework-agnostic.
### Step 5: Webhook Handler
InFlow delivers signed events to your registered webhook URL.
> 🚨 **CRITICAL MANUAL STEP:** The webhook URL **must be registered in the InFlow dashboard** by the user — there is no API for this. After implementing the handler, tell the user explicitly:
>
> *"Go to the InFlow dashboard, navigate to webhooks, register `https://yourdomain.com/api/webhooks/inflow` (or your equivalent URL), and copy the webhook secret into your `INFLOW_WEBHOOK_SECRET` env var. Until you do this, no events will be delivered."*
For local testing, suggest [ngrok](https://ngrok.com) or similar to expose `localhost` over HTTPS.
**Webhook payload shape — note the two `status` fields:**
```json
{
"eventId": "",
"webhookId": "",
"type": "TRANSACTION_UPDATED",
"status": "DELIVERED", ← OUTER: InFlow's delivery state. Ignore for fulfillment.
"data": {
"transactionId": "",
"approvalId": "",
"amount": 99.99,
"currency": "USDC",
"blockchain": "SOLANA",
"status": "PAID", ← INNER: actual transaction state. Use this for fulfillment.
"transactionHash": "0x...",
"created": "2026-01-01T00:00:00.000Z"
},
"created": "2026-01-01T00:00:00.000Z",
"delivered": "2026-01-01T00:00:01.000Z"
}
```
> **Critical disambiguation:** the envelope has TWO `status` fields:
> - **`event.status`** (outer) — InFlow's webhook delivery state: `PENDING` / `DELIVERED` / `FAILED` / `DISABLED`. This tells you whether InFlow successfully delivered the event. Don't branch on this for business logic.
> - **`event.data.status`** (inner) — the actual transaction or approval state: `PAID`, `INITIATED`, `PENDING`, `INSUFFICIENT_FUNDS`, `APPROVED`, `DECLINED`, etc. **This is what you check for fulfillment.**
**Event types:** `TRANSACTION_CREATED`, `TRANSACTION_UPDATED`
**The `data` field is a discriminated union:**
- If it has `requestId` and `type` (LOGIN/PAYMENT/etc.) → it's an `ApprovalResponse`
- If it has `transactionId`, `blockchain`, and `transactionHash` → it's a `TransactionResponse`
**Only fulfill orders when ALL of these are true:** `event.type === "TRANSACTION_UPDATED"`, the `data` field is shaped as a `TransactionResponse` (presence of `transactionId` is the simplest discriminator), and `event.data.status === "PAID"`. Do not generalize to "any TRANSACTION_* event with status PAID" — an `ApprovalResponse` payload may also have a `status` field (`APPROVED`/`PENDING`/etc.) and using it for fulfillment will crash or misfire.
**`data.status` values that matter (TransactionResponse):**
- `PAID` — payment completed (this is your "fulfill the order" signal)
- `INITIATED`, `PENDING` — in progress, do nothing
- `INSUFFICIENT_FUNDS`, `GENERAL_ERROR` — failed, notify user
- `REFUNDED`, `RETURNED` — money was returned
**Mandatory: HMAC signature verification.** Every webhook is signed with HMAC-SHA256. The signature is in the `x-inflow-signature` header. Verify it before processing.
```js
// Generic — adapt to whatever crypto library the project uses.
// Node.js example using built-in crypto module:
import crypto from 'node:crypto';
function verifyInflowWebhook(rawBody, signatureHeader, secret) {
// Guard against missing or malformed header — timingSafeEqual throws on length mismatch
if (typeof signatureHeader !== 'string' || signatureHeader.length === 0) return false;
if (!rawBody || !secret) return false;
const expected = crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
if (expected.length !== signatureHeader.length) return false;
// Constant-time compare to prevent timing attacks
return crypto.timingSafeEqual(
Buffer.from(expected),
Buffer.from(signatureHeader),
);
}
```
The same logic applies in any language: HMAC-SHA256 the raw request body using the webhook secret, hex-encode it, compare to the `x-inflow-signature` header.
**Critical:** verify against the **raw request body bytes**, NOT a re-serialized JSON object. If the framework parses JSON automatically, you must capture the raw body before parsing. The exact mechanism depends on the framework.
**Webhook handler responsibilities:**
1. Verify the signature → reject with HTTP 401 if invalid
2. Parse the JSON body
3. Check `eventId` against an idempotency store → skip if already processed (InFlow may retry the same event for up to 72 hours)
4. Look up your local order by `event.data.approvalId` or `event.data.transactionId` (see Order Correlation section above)
5. Branch on the FULL three-condition rule (do not skip any of these):
- **Fulfill** when ALL of: `event.type === "TRANSACTION_UPDATED"` AND `event.data.transactionId` is present (it's a `TransactionResponse`, not an `ApprovalResponse`) AND `event.data.status === "PAID"`
- **Mark failed** when `event.data.transactionId` present AND `event.data.status` is `INSUFFICIENT_FUNDS` / `GENERAL_ERROR` / `RETURNED`
- **Log only** for other event types or non-terminal statuses (`INITIATED`, `PENDING`, etc.)
- **NEVER fulfill on `event.status` (the OUTER delivery status) — that just means InFlow delivered the webhook successfully**
6. Return HTTP 200 to acknowledge
If the handler doesn't return 200, InFlow keeps retrying with exponential backoff for up to 72 hours.
### Step 6: Polling (Webhook Alternative)
If a webhook listener isn't possible (local dev, batch jobs, simple scripts), poll request status:
```http
GET https://api.inflowpay.ai/v1/requests/{requestId}
X-API-Key:
```
Returns the current `ApprovalResponse`. Poll every few seconds until `status` is no longer `PENDING`.
For full transaction details after approval:
```http
GET https://api.inflowpay.ai/v1/transactions/{transactionId}
```
Where `transactionId` comes from the approved `ApprovalResponse.transactionId`.
### Step 7: Policies (Enable 0-Click Headless Payments)
Policies are pre-approved spending rules. When a `HEADLESS` payment request includes a `policyId` and the request is within the policy's limits, it auto-approves immediately — no consumer interaction needed.
**Use policies for:**
- Autonomous AI agents that need to make purchases without per-transaction approval
- Recurring payments (subscriptions, automated top-ups)
- High-frequency low-value transactions
**Direct creation** (seller-initiated):
```http
POST https://api.inflowpay.ai/v1/policies
X-API-Key:
Content-Type: application/json
{
"type": "PAYMENT",
"action": "APPROVE",
"currency": "USDC",
"budget": 1000,
"threshold": 100,
"period": "MONTHLY",
"expires": "2026-12-31T00:00:00.000Z"
}
```
**Consumer-initiated request** (the consumer must approve the policy via their device):
```http
POST https://api.inflowpay.ai/v1/requests/policy
X-API-Key:
Content-Type: application/json
{
"userId": "",
"display": "FULL",
"userDetails": ["EMAIL"]
}
```
This returns an `ApprovalResponse` — same flow as login/payment. Consumer approves via SDK or mobile, and the policy becomes active.
**Policy fields:**
- `action` — `APPROVE`, `DECLINE`, `REVIEW`
- `period` — `DAILY`, `MONTHLY`, `YEARLY`, `ONCE`
- `budget` — total allowance for the period
- `threshold` — per-transaction maximum
- `spent` — current usage (read-only on `PolicyResponse`)
**CRUD:**
```http
GET /v1/policies
GET /v1/policies/{policyId}
POST /v1/policies
PUT /v1/policies/{policyId}
DELETE /v1/policies/{policyId}/delete
```
**Attach a policy to a payment:**
```json
{
"userId": "",
"amount": 50,
"currency": "USDC",
"display": "HEADLESS",
"userDetails": ["EMAIL"],
"policyId": ""
}
```
If the request is within budget and threshold, the response will already show `status: APPROVED`.
### Step 8: Wallet Read Operations
Read-only access to the seller's wallet state. Useful for dashboards, reconciliation, and balance checks.
```http
GET /v1/balances — all currency balances
GET /v1/balances/{currency} — single currency balance
GET /v1/transactions — paginated transaction history
GET /v1/transactions/{id} — single transaction
GET /v1/users/self — current authenticated user
```
All return JSON. See `references/api-reference.md` for full schemas.
---
## Verification
Run a smoke test to confirm everything works. Adapt the commands to whatever the project uses (npm scripts, curl, http file, etc.):
1. **API key auth** — call `GET /v1/users/self` with the configured `X-API-Key`. Should return the authenticated user. If 401, the key is wrong.
2. **User search** — call `POST /v1/users/search` with a known email. Confirm 200 + `userId`, or 404 if the user doesn't exist.
3. **Payment request** — initiate a small test payment to the known `userId`. Confirm the response contains a `requestId` and `status: PENDING`.
4. **Polling** (if implemented) — call `GET /v1/requests/{requestId}` and confirm the status updates as the consumer interacts.
5. **Webhook** (if implemented) — once a real event is delivered, check the handler's logs to confirm: signature verified, payload parsed, handler logic executed, HTTP 200 returned. (You can also use `GET /v1/events` to inspect past events and `POST /v1/events/{eventId}/resend` to replay one.)
If the user is in production, also recommend:
- A persistent idempotency store for `eventId`s (DB or Redis)
- Logging all webhook events for audit
- A dead-letter queue for failed webhook processing
---
## Agentic User Setup (No Existing Account)
If the user does NOT have an existing InFlow account, create an agentic (programmatic) user. This is a one-time setup and does NOT require existing authentication.
```http
POST https://api.inflowpay.ai/v1/users/agentic
Content-Type: application/json
{
"locale": "EN_US",
"timezone": "US/Pacific"
}
```
Returns:
```json
{
"userId": "",
"privateKey": "",
"locale": "EN_US",
"timezone": "US/Pacific",
"created": "...",
"updated": "..."
}
```
The `privateKey` is what goes in the `INFLOW_API_KEY` env var. **Store it securely** — it cannot be retrieved again.
---
## Idempotency
Before each step, check if the work is already done. Skip steps that are complete:
- If `INFLOW_API_KEY` is already in `.env` / `.env.example`, skip env setup
- If a webhook handler with HMAC verification already exists for InFlow paths, skip the webhook scenario
- If `inflow.js` is already loaded somewhere in the frontend, skip the SDK script tag
- If there's an existing helper module that wraps `api.inflowpay.ai` calls (look for `INFLOW_API_KEY` usage or `inflowpay.ai` in source), reuse it instead of creating a new one
- If `.env` / `.env.local` is not in `.gitignore`, add it
Always read the project before writing — don't duplicate existing logic.
---
## Final Summary (After Implementation)
After implementing, give the user a clear summary in this format:
1. **Files created or modified** — list each one with its purpose
2. **Env vars to set** — name + what each is for + where to get the values
3. **What flows are now active** — payment / login / register / webhook / polling / policies
4. **Manual steps the user must complete** — be explicit about:
- Getting the API key (from dashboard or via `POST /v1/users/agentic`)
- **Registering the webhook URL in the InFlow dashboard** (no API for this — flag prominently if a webhook handler was created)
- Copying the webhook secret into `INFLOW_WEBHOOK_SECRET`
- Confirming the production SDK URL with InFlow before going live (sandbox URL is in code by default)
5. **Test commands** — exact commands to verify each flow
6. **Next steps** — what to do after the integration is wired up
Keep the summary terse. The user should be able to complete the integration after reading it.