Integrate as a Partner

You are adding PayMe to the user's project, as a partner: a platform that onboards sellers, charges buyers on their behalf and may take a market_fee. This page is the procedure. Facts are on the pages it links to, so read them when you reach them, and never rely on memory for a field name (WRK-01).

Work through the phases in order. Don't skip phase 2 or 3: an integration built on guessed answers about flows and onboarding is the expensive kind of wrong.

Phase 1: Load the facts

Read Rules for Agents. They bind every later step.
Get your step list. With the MCP server, call plan_integration with role partner and the features chosen in phase 3. Without it, the Steps and Verify sections of the AI Toolkit are in order, and each page says which features it applies to.
When PayMe returns an error, use explain_error or the page for that code, such as error 420. Troubleshooting by Symptom covers the rest.

Phase 2: Understand the project

If the working directory has no project, ask where it lives first (Round 0).

Inspect, don't ask, for anything the code can tell you: language and framework, how routes and middleware are declared; database, migrations, and existing order, user and seller models; how secrets load; background jobs; test framework; frontend stack and its Content Security Policy; existing payment code.

Create the three record files now, and keep them current to the end.

Phase 3: Interview

If nobody is available to ask, take the stated defaults, list each one as unconfirmed in the decisions file, build what doesn't need a person, and report the rest as not proven. Never invent a credential, and don't skip WRK-06 or TOK-03. The same goes for approval in phase 4.

Ask with the structured question tool if you have one: at most four questions per round, each self-contained, with a recommended default offered first. Never ask for a secret value. Ask only what the code and docs can't answer, and write each answer to the decisions file as it arrives.

Round 0: where it lives (only if there's no project)

Question	Why it matters	Default
An existing codebase (where), or a new service (which stack)?	There's nothing to inspect otherwise	A new service, in its own repository

Round 1: scope

Question	Why it matters	Default
Seller onboarding: PayMe's white-label form, or `create-seller` with your own form?	The form needs PayMe to enable it, and you then never hold ID or bank data	`create-seller`
Checkout: hosted page, Hosted Fields, saved cards? (Several allowed)	Each adds browser code, a payment path and tests	Hosted page
Capabilities: refunds and voids, authorize and capture, subscriptions, balances and payouts, marketplace-wide saved cards? (Several allowed)	Each is a step page and endpoints to guard	Refunds and voids
If Hosted Fields: do sellers need 3D Secure?	Without it, part of the payment path is missing	Unknown: build it behind a switch, off, and ask PayMe

Round 2: commercials and the account

Question	Why it matters	Default
Default `market_fee`, 0 to 60, as a plain number?	It goes on every seller and sale, and `1%` fails	Configurable, 0
`seller_plan` values from your account manager?	An unknown value fails `create-seller`	Leave it out
Do you have a sandbox partner key and partner secret?	Nothing can be proven otherwise. See Get Your Dedicated Test Account	Build with PayMe mocked, and give the variable names
Is a terminal connected to your sandbox account?	Without one, every card fails with error 420	Ask them to confirm with PayMe before payment steps
How will PayMe reach your callback endpoint?	Seller callbacks arrive only at the Default Callback URL	One endpoint; a tunnel in development

Round 3: operations

Question	Why it matters	Default
Where will production run?	Decides where the partner secret lives	Secrets manager
Who calls your money-moving endpoints?	One shared key can't be revoked per person or audited	Named credentials with roles, and an audit log
One instance or several?	In-process locks prevent double charges in one process only	One instance, enforced at startup
Who resolves money movements with an unknown outcome?	A person must confirm against PayMe before anything is retried	The finance role

Draft What to Ask PayMe First for the person as facts come up. Don't wait until the end.

Phase 4: Plan, then confirm

Write a short plan mapping each chosen capability to files in their project: modules, routes, data changes and migrations, config keys, frontend changes, scheduled jobs, tests. Follow their conventions. Show it, and wait for approval before writing code. Ask before any destructive migration.

Phase 5: Build, in this order

Config and Transport
Money
Seller Onboarding
Checkout
Callbacks (Partner), the security-critical step, including scheduled reconciliation
Guard every endpoint you added (WRK-06). If the app has no login, stop and ask. If you're working unattended, implement named authentication and explicit roles before exposing these routes, and record your assumptions.
As chosen: Capture, Refund, Void, Saved Cards, Subscriptions, Balances and Payouts

Port from the reference code where it helps. Check your code against Implementation Traps before writing the connecting code.

Phase 6: Prove it

Port every test case for your role, and write the tests for your own code: Test Cases and Reference Code.
Run the whole test suite and the linter. Fix what you broke.
Check Implementation Traps again, and commission a reviewer who didn't write the code. Fix or record every finding.
Run the Readiness Preflight.
Run the Sandbox Walk-through with the person. Confirm every final state with a query.

Phase 7: Report

Fill in the Proof-of-Integration Report. Tell the person what was built by capability, which files changed, the config keys per environment, how to run the tests, which sandbox steps ran and which remain, and every departure from these docs with its reason. Point them to the Go-Live Checklist.

Keep a record

Create these in the user's project. They will ask for them.

INTEGRATION-DECISIONS.md, with three tables:

Questions and answers: number, question, answer, consequence in the code.
Decisions taken without asking: number, decision, why. List every default you chose, so it can be overturned.
Open issues: number, issue, status, owner and next step. Close rows rather than deleting them.

FIXES-MANIFEST.csv, one row per mistake (yours, the review's, the docs') and per action someone must take:

id,found_in,type,severity,description,what_needs_to_be_done,owner,status

type is one of: bug in our code, docs gap, docs defect, spec vs reality, finding from sandbox, hardening, action, question, verification.

SANDBOX-REPORT.md: only the steps that actually ran against PayMe, with pass, fail or finding, and the steps not yet run.

When something disagrees

If a page and PayMe's real behaviour disagree, trust what PayMe did, record it as spec vs reality, and tell the person. If nothing covers a question, say so and ask (WRK-04). Working style that helps: run independent work in parallel with narrow file ownership, browser-test buyer pages, report in the person's language, and never commit unless asked.