# Integrate InFlow payments into your application

This guide is for a coding agent working with a developer in their application
repository. InFlow payment SDKs connect applications to MPP and x402 payment
flows. A Seller accepts payments for resources; a Buyer pays to use resources.
An application can do either or both.

Follow one stage at a time. Explain findings, resolve decisions, and wait for the
developer before proceeding. Do not implement the entire guide in one turn.

## When the Directory guide coordinates this work

If this guide was opened by the
[Directory integration guide](https://directory.inflowpay.ai/integration.md),
read its `COMMERCE-INTEGRATION-PLAN.md` and reuse confirmed answers. Continue in
the same session. Skip a repeated welcome gate, but retain this guide's assessment,
design decisions, plan approval, implementation reviews, and verification.

During assessment, the child plan and the coordination plan are the only intended
writes. Save both before a handoff. Do not assess other integrations on behalf of
the coordinator or duplicate another child's implementation queue.

In coordinated mode, the related-integration pause suggestions below do not start
another guide. Record follow-up work for the selected child's turn. If a real
dependency blocks progress, return to the coordinator for a developer decision.
Do not add an unselected integration. At completion, return the child-plan path,
acceptance evidence, pending work, and next action to the coordinator.

## Working rules

- Follow repository instructions and preserve unrelated work.
- Inspect source before making claims. Dependencies alone do not prove a working
  payment integration.
- During assessment, write only the integration-plan file and, in coordinated
  mode, the coordination plan. Do not install
  packages, edit application code, create payment approvals, sign payment
  authorizations, initiate transfers, or run paid requests.
- Implement InFlow payments only. Keep ODP and AEP as separate workflows.
- Preserve existing authentication, authorization, checkout, and fulfillment.
  Payment does not replace application access control.
- Never ask for secrets in chat or record keys, tokens, wallet seeds, or private
  customer information in the plan. Direct the developer to secure local or
  deployment configuration.
- Obtain explicit authorization for payment tests, including environment, target,
  and spending limits. Sandbox does not by itself guarantee that a target or
  blockchain uses test funds.
- Commits, pull requests, deployment, and publication require authorization.
- A reply of `go` authorizes the next stated task, not unlimited implementation
  or spending. Ask for an explicit decision when a choice remains unresolved.

## Keep one durable plan from the start

Once the repository is confirmed, load the
[integration queue template](https://app.inflowpay.ai/integration-queue-template.md)
and create or reconcile `INFLOW-INTEGRATION-PLAN.md` there. Announce that it
holds interview answers, evidence, decisions, and the eventual execution plan.
Do not wait until implementation planning or ask a separate checkpoint question.

Preserve existing notes and unfinished tasks. If the template cannot be read or
the file cannot be saved, report the limitation; do not claim durable progress.

Track the stage as Interview, Assessment, Plan awaiting approval, Implementation,
or Verification. Before every response returning control to the developer, save
confirmed answers, selected and excluded capabilities, pending decisions,
source-backed findings, and the precise next action. Early planning is not
implementation approval.

Before suggesting another integration workflow, record the reason, destination,
and what to reassess on return. The developer may immediately leave the session.
On resumption, read the plan and verify current repository state. If it is absent,
reassess without assuming prior choices or completion.

## Sources and SDK selection

Start with the [InFlow Node SDK](https://github.com/inflowpayai/inflow-node),
its selected version's package documentation, public exports, and runnable
examples. Read the [MPP integration documentation](https://github.com/inflowpayai/inflow-node/tree/main/docs/mpp)
or [x402 integration documentation](https://github.com/inflowpayai/inflow-node/tree/main/docs/x402)
as applicable. Consult the authoritative [MPP](https://mpp.dev/)
and [x402](https://www.x402.org/) protocol documentation for wire requirements.

Node.js / TypeScript is the implemented SDK path for this guide. Do not infer
that another InFlow SDK is available from a repository name or organization
listing. Verify implementation, published packages, and role/protocol support
before proposing another language. If no suitable SDK is available, explain the
gap and ask how to proceed. Do not silently introduce a Node sidecar, port the
SDK, or invent another language's APIs.

For Node, begin with the package matching the selected role and protocol:

| Role   | MPP package               | x402 package               |
| ------ | ------------------------- | -------------------------- |
| Seller | `@inflowpayai/mpp-seller` | `@inflowpayai/x402-seller` |
| Buyer  | `@inflowpayai/mpp-buyer`  | `@inflowpayai/x402-buyer`  |

These are starting points, not a complete install command. Verify compatible
foundation libraries, peer dependencies, framework adapters, and runtime versions
against the selected release. Do not install both protocols merely because both
appear in this table.

Protocol specifications govern wire behavior; SDK source establishes supported
APIs and mechanisms; the application's source establishes its current behavior;
developer decisions establish business policy and scope. Report conflicts.
Examples explain integration patterns but do not define this application's
pricing, spending authority, or failure policy.

## 1. Welcome

Begin with a short introduction:

> Welcome to the InFlow payments integration process. We will find where your
> application should accept payments, make payments, or both. We will inspect
> the current code, choose the appropriate protocol support, and agree on a plan
> before implementing it. Existing checkout and authentication will be preserved.

Explain the staged process and that live payments need separate authorization.
Pause: "Next step: type `go` to begin the interview."

## 2. Confirm the target and goals

Ask in small groups and reuse answers already provided:

1. Which repository and application should receive the integration?
2. Should it accept payments as a Seller, make payments as a Buyer, or both?
3. What should become possible? Ask for a real application operation, such as
   charging for report generation or paying an external search API.
4. Is this a first payment integration or an update to existing MPP/x402 support?
5. Would you like both MPP and x402, x402 only, or MPP only? Recommend both for
   broader caller compatibility, while respecting existing requirements and the
   developer's choice. If unsure, keep the choice pending through assessment.
6. Are ODP or AEP already planned? Existing implementations will be inspected.

Explain that MPP and x402 are protocols, not synonyms for a blockchain, currency,
or payment method. Do not ask the developer to choose from a list of unrelated
protocol and network names.

Recommend Sandbox for initial integration checks and ask about the intended
deployment environment. Confirm the framework and SDK recommendation from source
rather than making the developer answer questions the repository can resolve.
Save the answers and pause before scanning.

## 3. Discover existing payment opportunities

Announce the read-only application assessment. Inspect routes, business logic,
pricing, authentication, checkout, storage, fulfillment, outbound HTTP clients,
existing payment integrations, deployment configuration, and tests.

For Sellers, look for paid products, browser checkout, downloads, API services,
subscriptions, and metered features. Trace them to authoritative prices,
customer entitlements, and fulfillment logic. Do not assume every route should
become paid.

For Buyers, inspect outbound requests, purchasing operations, existing approval
experiences, credential custody, and spending controls. Distinguish a client that
explicitly calls one paid Service from a shared HTTP client used throughout the
application.

Present concrete candidates using actual findings:

> Your application charges for reports through browser checkout and exposes
> a report-generation API. Should agent payments cover report generation,
> downloading completed reports, or both?

Do not repeat those details unless verified. Use a short selection table:

| Capability found       | Existing behavior and evidence   | Proposed integration                                    | Developer selection |
| ---------------------- | -------------------------------- | ------------------------------------------------------- | ------------------- |
| Report-generation API  | Route, price source, and handler | Accept payment for a requested report                   | Include or exclude  |
| External search client | Request path and existing limits | Pay supported search requests within an approved policy | Include or exclude  |

Replace illustrative rows with actual findings. A capability may not have a
suitable callable API. Explain any application API work needed and ask before
including it. Reuse underlying data and business behavior instead of scraping
the application's own pages or duplicating checkout.

Report existing protocol support, framework compatibility, payment-related state,
and unresolved decisions with source locations. Separate verified source behavior
from runtime behavior not exercised. Save the assessment and pause.

## 4. Select capabilities and resolve payment decisions

Confirm the selection from the assessment. Do not ask again about choices already
answered. Design only the selected capabilities.

### Protocol and payment choices

Preserve working MPP/x402 support. Recommend both to support callers using either
protocol, and ask the developer to select Both, x402 only, or MPP only. Reuse a
choice already confirmed. Verify that the selected SDK and application can support
that choice; explain any gap before planning. Do not enable both automatically.

Give concrete ecosystem examples: MPP supports payments from Stripe Link through
its [Stripe integration](https://mpp.dev/payment-methods/stripe), while x402 supports
networks including [Base and Solana](https://docs.x402.org/core-concepts/network-and-token-support).
These illustrate the protocols, not a promise that the InFlow integration enables
every ecosystem method. This guide must verify the selected InFlow SDK, payment
method, network, and deployment support before recommending a configuration.

For Sellers, determine which options the service can actually accept through each
protocol using the selected SDK and configured service capabilities. For Buyers,
compare destination challenges with methods the Buyer is configured and allowed
to use. Do not reuse the ODP option enumeration as a compatibility matrix.

When both protocols are selected, share appropriate pricing and fulfillment logic
while keeping each protocol's request handling explicit. A request must not
unintentionally pass through two independent charging paths.

Verify support for the intended payment model, such as a single charge or a
subscription, separately for each protocol and method. Do not promise the same
features everywhere or add recurring billing merely because an SDK exposes it.

### Seller decisions

Resolve:

- Which operations are paid, and which stay free?
- What event is charged: a request, a generated result, a download, usage, or a
  separately approved recurring arrangement?
- Where do prices come from, which currencies apply, and when is an amount
  calculated and bound to a request?
- Which account, tenant, or customer receives the resulting entitlement?
- What authentication and permission checks remain required?
- When may the business handler execute relative to verified payment success?
- How do repeated requests avoid duplicate charges and duplicate fulfillment?
- What should happen if payment succeeds but fulfillment fails?

Do not invent refunds or assume every failure means no charge occurred.
Determine what the SDK and payment API can establish about an ambiguous outcome,
then ask for the application's business decision where needed.

### Buyer decisions

Resolve:

- Which destinations and operations may be paid for?
- Which currencies and payment methods are permitted?
- What per-request or aggregate limits are needed, and who authorizes them?
- When should the application request human approval rather than pay automatically?
- Where are InFlow credentials or supported wallet keys held?
- How are approval, pending, cancellation, timeout, and terminal results presented?
- When is replaying the original request safe, including its method and body?

Inspect the chosen client's side effects. Some wrappers can intercept shared or
global HTTP calls and automatically pay compatible challenges. Prefer an explicitly
scoped client when it fits; do not enable automatic payment or a global wrapper
without explaining and obtaining approval for its scope. Use verified hooks or
application controls rather than inventing SDK options.

### Account and environment setup

Determine prerequisites for the selected API path, not just the Buyer/Seller label:

- Seller configuration APIs used by the standard Seller integration require an
  InFlow Seller account. A Developer account key does not satisfy that requirement.
- Authenticated InFlow Buyer APIs can be used by an existing Seller account too.
  Recommend a Developer account for a buyer-only API-key integration; do not
  require a second account solely to act as a Buyer.
- The SDK also contains a distinct unauthenticated x402 facilitator path.
  Do not generalize its account requirements to the standard Seller client.
  Confirm whether that specialized path actually fits before proposing it.

Direct the developer to the chosen environment:

| Environment | Account and credential setup |
| ----------- | ---------------------------- |
| Sandbox     | https://sandbox.inflowpay.ai |
| Production  | https://app.inflowpay.ai     |

Set `environment` explicitly in the integration. The Node SDK defaults to
production when omitted. Match the environment to the account credentials and
confirm protocol/network configuration independently. Do not assume a Sandbox
API endpoint makes an arbitrary external Seller or blockchain a test environment.

Keep API keys on the appropriate trusted side of the application. Never put a
Seller API key in browser-delivered code. Use the application's existing secret
configuration and explain how the developer supplies values without disclosing
them in chat, source control, examples, or the plan.

### Existing authentication and related protocols

Payment does not replace login, permissions, tenant isolation, or AEP enrollment.
Trace middleware and header handling end to end. Preserve required authentication
before allowing protected fulfillment; do not collect payment for a request
already known to be unauthorized. Verify coexistence rather than assuming that
AEP and payment credentials can use the same header.

If AEP or ODP is absent, it is not automatically a Payments integration failure.
When the developer plans it, offer to continue Payments with the current
application or pause for its separate workflow:

- [AEP integration](https://www.aep.foundation/integration.md)
- [ODP integration](https://www.offeringprotocol.org/integration.md)

Save the handoff state before offering the switch. Read the destination guide;
if unavailable, explain that instead of inventing it. Do not implement the other
protocol inside this plan. Record any needed ODP payment-advertisement changes
as a follow-up for the ODP workflow.

## 5. Complete the executable plan

Expand `INFLOW-INTEGRATION-PLAN.md` from the saved assessment and decisions.
Separate Buyer and Seller work when both are needed. Record:

- Selected capabilities, excluded capabilities, and approved application API work.
- SDK and foundation dependency versions and their authoritative source references.
- Protocols, methods, pricing source, environment, and credential configuration.
- Authentication, authorization, payment, and fulfillment ordering.
- Spending and approval decisions for Buyer behavior.
- Retry, idempotency, duplicate-fulfillment, and ambiguous-outcome handling.
- Relevant persistence and concurrency requirements.
- Tests of new behavior and regression checks for affected existing flows.
- Separate deployment and authorized end-to-end verification tasks.

Trace each requirement to the actual integration boundary. Reuse SDK and
application functionality instead of writing a parallel payment engine.
Do not redesign transaction storage or introduce a background reconciliation
system without demonstrating the need and obtaining approval.

Set the stage to Plan awaiting approval. Present the plan, open decisions,
verification approach, and first task. Wait for approval before changing code.

## 6. Implement one task at a time

Follow the queue template's seven-step review process. Implement coherent slices,
trace the real request paths, and challenge security-sensitive defaults.

After each task, update the plan before returning control. Report the behavior
implemented, review findings fixed, commands actually run, failures or limitations,
and the specific next task. Invite the developer to type `go` to continue.

Stop for decisions that change the approved scope. A request to implement payment
support is not permission to initiate a payment, deploy, or publish a package.

## Exit criteria to generate in the plan

End the generated plan with two separate, cumulative acceptance groups:

1. **Project acceptance:** derive the project's prescribed unit tests, integration
   tests, coverage thresholds, static analysis, regression checks, and other
   agreed quality gates from its source and instructions. These remain required.
2. **InFlow acceptance:** verify the integration against a running system using
   InFlow CLI and the role-specific checks below. These do not replace project
   tests or justify lowering their thresholds.

For every criterion, record the exact command or procedure, environment, target,
prerequisites, expected result, evidence, and state. Verify CLI syntax and options
against its installed version before generating runnable commands. Command names
below are examples, not complete invocations. Never save secrets in command logs.

For a Seller integration, generate authorized CLI checks against a running paid
endpoint for each selected protocol: `inflow mpp pay` and/or `inflow x402 pay`.
Check the actual method, body, authentication, challenge, payment result, and
fulfillment. Verify an unpaid or unsuccessful request cannot obtain the protected
result. Confirm environment, target, and spending limits before execution.

For a Buyer-only integration, the InFlow CLI does not exercise the application's
Buyer code. Keep a CLI check against a compatible controlled Seller as a reference,
and require a real request from the implemented Buyer to that Seller as well.
Record these as distinct results. Do not build a Seller into a Buyer application
solely to satisfy a demonstration.

Distinguish implementation complete, local verification, deployed verification,
and external publication. Obtain explicit authorization for enrollment, credential
changes, payments, and publication. Pending approval or unavailable infrastructure
is not a passing criterion. A developer-approved deferral remains visible in the
handoff rather than being reported as end-to-end success.

## 7. Verify and hand off

Run the application's prescribed checks and relevant integration tests.
Use controlled fixtures and test environments without performing real purchases.
A real payment test, including one expected to use test funds, requires explicit
agreement on the environment, target, operation, and spending limits.

For the selected paths, verify:

- Free requests pass without triggering payment.
- Unpaid requests to paid resources yield the expected protocol challenge.
- Invalid or unsuccessful payment does not unlock protected fulfillment.
- Successful payment allows the intended operation and result.
- Existing authentication and authorization remain enforced.
- Retries and duplicates follow the agreed charging and fulfillment policy.
- Pending, cancellation, expiry, timeout, and ambiguous outcomes are handled
  without assuming an error proves that no payment occurred.
- Buyer limits and approval controls apply before payment authorization.
- Request replay preserves the intended method, body, and safe credential scope.

Distinguish tests against mocks from real counterpart integration. A mock that
repeats an unverified assumption does not establish protocol compatibility.
If authorized end-to-end testing cannot run, state the gap rather than marking
it passed.

Check affected existing browser checkout, API authentication, permissions, and
fulfillment flows. Use existing tests or targeted checks rather than requiring
an unrelated test framework. Review every changed file after verification and
confirm the tested tree matches the delivered tree.

Hand back the plan path, files changed, exact checks and results, local versus
deployed evidence, remaining risks, and the precise next action. Deployment and
publication require separate authorization.

## Run this guide again

Reassess current code on every run. A developer may add another protocol, introduce
AEP, select more paid operations, or add Buyer behavior to a Seller application.
Preserve working integrations, confirm the new goal, and plan only the approved
changes. Earlier completion markers do not replace verifying current behavior.