Integrate as a Direct Seller

You are adding PayMe to the user's project for a business that sells on its own account. Its only secret PayMe credential is its MPL. It has no partner secret, so it can't check callback signatures, and every callback is confirmed by query. 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).

Phase 1: Load the facts

  1. Read Rules for Agents. They bind every later step.
  2. Get your step list. With the MCP server, call plan_integration with role seller 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.
  3. 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

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

Keep three record files in the project from now on: INTEGRATION-DECISIONS.md, FIXES-MANIFEST.csv and SANDBOX-REPORT.md. Their format is on the partner page, under Keep a record, and applies to you too.

Phase 3: Ask the person

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.

One message with all the questions. Ask only what the code can't answer, never ask for a secret value, and record each answer.

Question Why it matters Default
Checkout: hosted page, Hosted Fields, saved cards? Each adds browser code, a payment path and tests Hosted page
If Hosted Fields: does the account need 3D Secure? Without it, part of the payment path is missing Unknown: ask PayMe
Capabilities: refunds and voids, authorize and capture, subscriptions? Each is a step page and endpoints to guard Refunds and voids
Do you have a dedicated sandbox account, with its MPL and, for Hosted Fields, its public key? 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 it? Without one, every card fails with error 420 Ask them to confirm with PayMe
What public address will PayMe post to, and what address do buyers return to? Callbacks need one, and return pages need the other A tunnel in development

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

  1. Config and Transport
  2. Money
  3. Checkout
  4. Callbacks (Direct Seller), the security-critical step, including the scheduled re-check and the status table it links to
  5. 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.
  6. As chosen: Capture, Refund, Void, Saved Cards, Subscriptions

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

Phase 6: Prove it

  1. Port every test case for your role, and write the tests for your own code: Test Cases and Reference Code.
  2. Run the whole test suite and the linter. Fix what you broke.
  3. Commission a reviewer who didn't write the code, against Implementation Traps and these docs. Fix or record every finding.
  4. Run the Readiness Preflight.
  5. 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.

When something disagrees

If a page and PayMe's real behaviour disagree, trust what PayMe did, record it, and tell the person. If nothing covers a question, say so and ask (WRK-04).