• 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.

USDC

userDetails

["EMAIL"]

FULL

inflow.js

HEADLESS

userId

• 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

X-API-Key

• 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)

• 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.

• 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).

• 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).

• Vue components and composables run in the browser. Use

  server/api/*

  route handlers or

  server/utils/*

  . Never read

  INFLOW_API_KEY

  from a

  <script setup>

  block in a

  .vue

  file.

• All have a server/client split. The rule is the same:

  INFLOW_API_KEY

  is read only inside the framework's server boundary (loader, action, server route, etc.), never in component code.

• Git history (especially after a

  git push --force

  "fix")
• Browser devtools (anyone can open them)
• Browser extensions (they read your scripts)
• Error reports / crash dumps shared in tickets
• Screenshots posted in Slack / GitHub / Stack Overflow
• Build artifacts uploaded to CDNs
• Deployed preview URLs that get crawled

1. Set env vars (Step 1) —

   INFLOW_API_KEY

   , optionally

   INFLOW_WEBHOOK_SECRET

2. Identify the consumer (Step 2) —

   POST /v1/users/search

   with email/mobile/username → get

   userId

3. Create the payment with

   display: HEADLESS

   (Step 3) — pass

   policyId

   if you have one for 0-click; otherwise the consumer gets a mobile/email approval prompt
4. Persist your correlation key — store

   { yourOrderId, requestId, transactionId? }

   so the webhook handler can look up the right order. The webhook payload only carries InFlow's IDs; you must map them back to your business object.
5. Wait for confirmation — either:
   • Webhook handler (Step 5) — recommended for production. Verify HMAC, idempotency by

     eventId

     , fulfill on

     event.data.status === "PAID"

     (with the discriminator check)
   • OR polling (Step 6) — for scripts, batch jobs, local dev. Call

     GET /v1/requests/{requestId}

     until status leaves

     PENDING

inflow.js

policyId

┌──────────────────────────────────────────────────────────────────┐
│ Frontend (browser)                                               │
├──────────────────────────────────────────────────────────────────┤
│ 1. Collect consumer email at checkout                            │
│ 2. Click "Pay with InFlow" → POST to YOUR /api/inflow/checkout   │
│ 3. Receive { requestId } from your backend                       │
│ 4. Render popup: new InFlow.Request(requestId).render({...})     │
│ 5. statusCallback fires when consumer approves                   │
│ 6. Show "processing..." (DO NOT fulfill yet)                     │
└──────────────────────────────────────────────────────────────────┘
                            │
                            ▼
┌──────────────────────────────────────────────────────────────────┐
│ Backend (your /api/inflow/checkout endpoint)                     │
├──────────────────────────────────────────────────────────────────┤
│ 1. Receive { email, amount } from frontend                       │
│ 2. POST /v1/users/search { email } → get userId                  │
│    (if 404 → POST /v1/requests/register first)                   │
│ 3. POST /v1/requests/payment {                                   │
│      userId, amount, currency: "USDC",                           │
│      display: "FULL", userDetails: ["EMAIL"]                     │
│    }                                                             │
│ 4. Return { requestId } to frontend                              │
└──────────────────────────────────────────────────────────────────┘
                            │
                            ▼
┌──────────────────────────────────────────────────────────────────┐
│ Backend (your /api/webhooks/inflow endpoint)                     │
├──────────────────────────────────────────────────────────────────┤
│ 1. Receive POST from InFlow with x-inflow-signature header       │
│ 2. Verify HMAC-SHA256 signature → 401 if invalid                 │
│ 3. Check eventId against idempotency store → skip if seen        │
│ 4. Fulfill ONLY if ALL three are true:                           │
│    a. event.type === "TRANSACTION_UPDATED"                       │
│    b. event.data.transactionId is present                        │
│       (i.e. data is a TransactionResponse, not Approval)         │
│    c. event.data.status === "PAID"                               │
│    (use INNER data.status, NOT outer event.status)               │
│ 5. Return HTTP 200                                               │
└──────────────────────────────────────────────────────────────────┘

Two

status

fields, two meanings. The webhook envelope has an outer

event.status

(

DELIVERED

/

FAILED

/

PENDING

/

DISABLED

— InFlow's delivery state) and the inner

event.data.status

(the actual transaction state like

PAID

/

PENDING

/

INSUFFICIENT_FUNDS

). Always check

event.data.status

for fulfillment decisions. See Step 5 for details.

1. Get an

   INFLOW_API_KEY

   (from InFlow dashboard, or create an agentic user — see "Agentic User Setup" below)
2. Register the webhook URL

   https://yourdomain.com/api/webhooks/inflow

   in the InFlow dashboard (no API for this)
3. Get the

   INFLOW_WEBHOOK_SECRET

   from the InFlow dashboard after registering the URL

references/

• references/overview.md

  — Platform concepts, approval model, FULL vs HEADLESS display modes

• references/flows.md

  — 8 worked-out integration flows with HTTP examples

• references/api-reference.md

  — Every endpoint, every schema, every enum value

1. Read the project — detect language and framework via

   package.json

   ,

   requirements.txt

   ,

   go.mod

   ,

   Cargo.toml

   , etc. Use whatever HTTP client and web framework already exists. Do not impose Express, Next.js, React, or any specific framework.
2. Pass the Hard Backend Gate (see the "🛑 Hard Backend Gate" section earlier in this file) — name the server-only surface where the API key will live. If there isn't one, scaffold one (with the user's agreement) before continuing.
3. Confirm the user has an API key — if not, walk them through the agentic user setup at the bottom of this file.
4. Confirm the project type — pure backend / fullstack web app / CLI / agent / worker. Pure-frontend projects are NOT a valid type — see the Hard Backend Gate.
   • Pure backend → Server payment + webhook (or polling)
   • Fullstack / web app → Server payment + frontend SDK + webhook
   • CLI / agent / worker → Headless payment + webhook (or polling) + maybe policies for 0-click

userId

userId

POST https://api.inflowpay.ai/v1/users/search
X-API-Key: <INFLOW_API_KEY>
Content-Type: application/json

{ "email": "alice@example.com" }

{ "userId": "8a5c2948-9e08-439e-a7a6-9f0ee335f566" }

POST https://api.inflowpay.ai/v1/requests/register
X-API-Key: <INFLOW_API_KEY>
Content-Type: application/json

{
  "display": "FULL",
  "userDetails": ["EMAIL", "NAME"]
}

⚠️ API quirk:

RegisterRequest

lists

userId

as optional (only

display

and

userDetails

are required per the OpenAPI spec), but its semantics for a true new-user registration flow are not documented. Do not invent a UUID. Try the call without

userId

first; if the API rejects it, the user must obtain a provisional

userId

from InFlow support or check vendor docs. Treat this as vendor-ambiguous and surface the ambiguity to the user — do not silently work around it.

ApprovalResponse

requestId

requestId

• email

  — RFC email format

• mobile

  — E.164 format like

  +15551234567

• username

  — 3-16 chars, alphanumeric +

  -_

userDetails

BIRTHDATE

DEPOSIT_ADDRESSES

EMAIL

MOBILE

NAME

NATIONAL_ID

PHYSICAL_ADDRESS

USERNAME

EMAIL

POST https://api.inflowpay.ai/v1/requests/payment
X-API-Key: <INFLOW_API_KEY>
Content-Type: application/json

{
  "userId": "<consumer-uuid-from-Step-2>",
  "amount": 99.99,
  "currency": "USDC",
  "display": "FULL",
  "userDetails": ["EMAIL"]
}

{
  "requestId": "<uuid>",
  "type": "PAYMENT",
  "status": "PENDING"
}

amount

currency

display

userDetails

userId

policyId

99.99

• 4xx → user error (missing field, invalid format, user not found). Return the error to the caller, don't retry.
• 5xx / network → transient. Retry with exponential backoff (max 3 attempts) before failing the checkout.

requestId

• FULL

  → hand

  requestId

  to the frontend SDK (Step 4)

• HEADLESS

  → wait for the webhook (Step 5) or poll

  GET /v1/requests/{requestId}

  (Step 6)

inflow.js

requestId

<script src="https://sandbox.inflowpay.ai/sdk/inflow.js"></script>

⚠️ 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.

// 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.
    }
  }
});

requestId

🚨 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."

localhost

status

{
  "eventId": "<uuid>",
  "webhookId": "<uuid>",
  "type": "TRANSACTION_UPDATED",
  "status": "DELIVERED",          ← OUTER: InFlow's delivery state. Ignore for fulfillment.
  "data": {
    "transactionId": "<uuid>",
    "approvalId": "<uuid>",
    "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.

TRANSACTION_CREATED

TRANSACTION_UPDATED

data

• If it has

  requestId

  and

  type

  (LOGIN/PAYMENT/etc.) → it's an

  ApprovalResponse

• If it has

  transactionId

  ,

  blockchain

  , and

  transactionHash

  → it's a

  TransactionResponse

event.type === "TRANSACTION_UPDATED"

data

TransactionResponse

transactionId

event.data.status === "PAID"

ApprovalResponse

status

APPROVED

PENDING

data.status

• 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

x-inflow-signature

// 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),
  );
}

x-inflow-signature

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

HEADLESS

policyId

• Autonomous AI agents that need to make purchases without per-transaction approval
• Recurring payments (subscriptions, automated top-ups)
• High-frequency low-value transactions

POST https://api.inflowpay.ai/v1/policies
X-API-Key: <INFLOW_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"
}

POST https://api.inflowpay.ai/v1/requests/policy
X-API-Key: <INFLOW_API_KEY>
Content-Type: application/json

{
  "userId": "<consumer-uuid>",
  "display": "FULL",
  "userDetails": ["EMAIL"]
}

ApprovalResponse

• 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

  )

GET    /v1/policies
GET    /v1/policies/{policyId}
POST   /v1/policies
PUT    /v1/policies/{policyId}
DELETE /v1/policies/{policyId}/delete

{
  "userId": "<consumer-uuid>",
  "amount": 50,
  "currency": "USDC",
  "display": "HEADLESS",
  "userDetails": ["EMAIL"],
  "policyId": "<policy-uuid>"
}

status: APPROVED

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.)

• A persistent idempotency store for

  eventId

  s (DB or Redis)
• Logging all webhook events for audit
• A dead-letter queue for failed webhook processing

• 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

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