AI Toolkit

This guide takes a person or an AI agent from nothing to a proven PayMe integration: the procedure, the rules, the checks, the code and the test cases. It works in any language.

Choose your path

Partner Direct seller
Who A marketplace or platform that onboards other businesses and charges buyers on their behalf A business selling on its own account
Credentials Partner key and partner secret, from partners@payme.io, plus each seller's MPL and public key Your MPL, plus your public key for Hosted Fields
Callback security Check the signature on sale callbacks, then confirm by query Confirm every callback by query: you have no secret to check a signature with
Extra steps Seller onboarding, fees, balances and payouts None
Start at Integrate as a Partner Integrate as a Direct Seller

Why callback security differs: payme_signature is computed with partner credentials, so only a partner can check it. For both roles, a valid signature isn't proof of payment, and no callback body is ever trusted. Both end by asking PayMe what happened.

Start here as a partner

You need Who supplies it Detail
Sandbox partner key and partner secret PayMe, from partners@payme.io Get Your Dedicated Test Account
A terminal on the sandbox account PayMe What to Ask PayMe First
The Default Callback URL PayMe sets it to a public address you give it What to Ask PayMe First and the tunnel recipe
Each seller's MPL and public key Your create-seller call returns them Seller Onboarding

To check that the sandbox account can complete the Sandbox Walk-through:

  1. Run the Readiness Preflight. Its read-only call shows that the credentials work.
  2. Onboard a test seller and pay once on the hosted page with a test card. A completed payment shows a terminal is connected. Error 420 means none is.
  3. Ask PayMe for what you can't set yourself, such as the Default Callback URL, subscriptions, and a test seller ready for a successful payout. The full list says which ones your scope needs.

What's here

Section What it holds
Start Get Your Dedicated Test Account, What to Ask PayMe First, Rules for Agents
Partner and Seller The full procedure for each role. AI agents can install these as skills: see Build with AI
Steps The rules, traps and order for each part of the build, linking to the API reference for fields
Verify Test cases and reference code, preflight, sandbox walk-through, go-live checklist and the proof report
Errors One page per common error, such as error 420, and Troubleshooting by Symptom

For an AI agent, the MCP server's plan_integration tool returns the steps for a role and a set of features, and explain_error returns the page for an error code. Every page also has a Markdown version: add .md to its address.

Install the skills

Skills are procedures your coding agent keeps and follows. The skills catalog lists them; each one is a page of these docs and links to the live pages it relies on.

npx skills add https://docs.payme.io/

That command asks which skills to install and where. An agent working alone can name them, so nothing asks. Set --agent to your own tool, such as Claude Code or Codex:

npx skills add https://docs.payme.io/ --skill <skill-name> --agent claude-code --yes
npx skills add https://docs.payme.io/ --skill <skill-name> --agent codex --yes

Connect the MCP server

MCP server URL: https://docs.payme.io/mcp

It uses Streamable HTTP (MCP protocol 2026-07-28, and 2025-11-25 or earlier) and is read-only. Public docs need no key or sign-in.

It needs an MCP client, not a web fetch (a GET answers 405). A chat app generally needs a person to add this URL in its settings; a coding agent with a command line can often register it itself. Without that, read each page's Markdown version, or the normal page if your tool can't open it.

Adding a server may not give the current session its tools: in one Codex test a desktop chat didn't get them, while a new Codex CLI process did. If they don't appear, start a new session or process, then confirm by calling a tool such as list_products.

What the MCP server can do

For an integration, start with plan_integration: it lists the pages to follow for your role (partner, seller) and features (hosted-page, hosted-fields, saved-cards, authorize-capture, refunds, subscriptions, payouts). When PayMe returns an error code, explain_error gives the page that answers it.

Tool What it does
search_docs Full-text search across the guide and API endpoint pages you can read.
get_page Returns one documentation page — guide or API endpoint — as Markdown, with its prerequisites and related pages as links.
list_products Lists the pages to read first and every documented product.
list_pages Lists every page of one product — guides and API endpoints — in reading order, by category: the category id and title, page type ("guide" or "endpoint"), slug, title, description, summary when the page has one, method + path for an endpoint, and the absolute page URL to pass to get_page.
list_endpoints Lists the API endpoints of one product, by category: method + path, title, and the category/slug to pass to get_endpoint.
get_endpoint Returns one API endpoint: its full Markdown reference (method and URL per environment, prerequisites, the credentials it documents, parameters, request fields and example, code samples, every response) followed by its OpenAPI operation as compact JSON.
get_openapi Each category (section) of an api-reference product has its own OpenAPI 3.1 file.
plan_integration Lists the pages to follow for an integration, in reading order, for your role ("partner" or "seller") and the features you need.
explain_error Returns the page that answers one PayMe error code, as Markdown: what it means and what to do.

Reference code and test cases

The integration kit lists every file of the reference code and test cases, with its address relative to that folder. All of it carries the MIT licence.

Procedures

Start

Partner

Seller

Steps

Checklists and errors

Verify

Errors

Set up a coding tool

The steps here and for chat apps come from each tool's own documentation. Menu names change, so follow your tool's documentation if a step looks different.

Claude Code

claude mcp add --transport http payme-docs https://docs.payme.io/mcp

Codex

codex mcp add payme-docs --url https://docs.payme.io/mcp

Cursor

Add to .cursor/mcp.json in your project, or ~/.cursor/mcp.json for every project:

{
  "mcpServers": {
    "payme-docs": {
      "url": "https://docs.payme.io/mcp"
    }
  }
}

VS Code

Add to .vscode/mcp.json in your project:

{
  "servers": {
    "payme-docs": {
      "type": "http",
      "url": "https://docs.payme.io/mcp"
    }
  }
}

GitHub Copilot CLI

copilot mcp add --transport http payme-docs https://docs.payme.io/mcp

Gemini CLI

gemini mcp add --transport http payme-docs https://docs.payme.io/mcp

Grok Build

grok mcp add --transport http payme-docs https://docs.payme.io/mcp

Windsurf and Devin Desktop

Open the MCP config file from the Cascade panel and add:

{
  "mcpServers": {
    "payme-docs": {
      "serverUrl": "https://docs.payme.io/mcp"
    }
  }
}

Set up a chat app

Claude (claude.ai and desktop app)

Go to Customize → Connectors, select + Add, then Add custom connector. Enter a name and the MCP server URL, and choose No sign in under Authentication. On Team and Enterprise plans, an Owner adds it under Organization settings → Connectors, then members select Connect under Customize → Connectors.

ChatGPT

Go to Plugins, select the plus button, then Add custom MCP server. Enter a name and the MCP server URL, choose No authentication, accept the risk warning and select Create as a plugin. Install the plugin, then pick it with @ in a new chat. Availability depends on your plan and workspace.

Gemini

On gemini.google.com, open Settings → Connected Apps. Under Custom apps, select Add a custom app and enter the MCP server URL. Google currently limits this to personal Google accounts, people aged 18 or over in the US, and English, with Keep Activity on.

Grok

Go to grok.com/connectors, select New Connector, then Custom, and enter the MCP server URL. Custom connectors need a paid plan. On Grok Business and Enterprise, a team admin adds the connector first.

Perplexity

Open Plugins (or Customize → Connectors), then select Add custom → Add MCP connector → Remote. Enter a name and the MCP server URL. Under Advanced, choose None for authentication and Streamable HTTP for the transport. In an organization, an admin must allow members to add custom connectors.

Mistral

Open Connectors, select + Add Connector, then the Custom MCP Connector tab. Enter a name without spaces and the MCP server URL, and choose No authentication. Adding one requires an administrator.

Machine-readable files

Example prompts

Tips