Skip to main content

Build with AI agents

Von Payments treats AI agents as first-class developer participants. Every part of the integration — SDKs, MCP server, CLI, errors, discovery endpoints — is designed for an autonomous agent to use the same way a human developer would, without hand-holding.

This isn't a wrapper layer. It's how the product was built.

What makes Von Payments agent-friendly​

Every error response includes a code, a one-line fix, and a link to the docs page that explains it. Agents read the code to branch, the fix to act, and don't need to escalate to a human unless the fix tells them to.

{
  "error": "Currency 'USDD' is not supported.",
  "code": "validation_error",
  "fix": "Check the request body against the API reference",
  "docs": "https://docs.vonpay.com/integration/create-session"
}

The SDK wraps this in a typed envelope (VonPayError.selfHeal.llmHint + selfHeal.nextAction) so agents using @vonpay/checkout-node get the same signal without parsing JSON.

Every /.well-known/ and llms.txt endpoint is unauthenticated. An agent can self-orient against any Von Payments domain by fetching two URLs.

The four agent surfaces​

SurfaceUse when
MCP server (@vonpay/checkout-mcp)Agent runs in Claude Desktop, Cursor, Claude Code, or any MCP client. Native tool calling.
CLI (@vonpay/checkout-cli)Agent shells out to commands. --json everywhere; doctor --for-llm for env self-diagnosis.
Node SDK + Python SDKAgent writes code that calls the SDK directly. Typed errors with self-heal envelope.
REST APIAgent generates HTTP calls. Discovery via /.well-known/vonpay.json + /llms.txt.

Quickstart for agents​

1. Discover the API (zero auth)​

curl https://checkout.vonpay.com/.well-known/vonpay.json
curl https://checkout.vonpay.com/llms.txt

The discovery endpoint returns the current API version, SDK package names, MCP package, docs URLs. llms.txt returns a concise LLM-readable reference of every public endpoint.

2. Pick a surface and authenticate​

For MCP — install @vonpay/checkout-mcp in your client config and set VONPAY_API_KEY to a vp_sk_test_* key. Restart the client; tools appear.

For CLI — npx @vonpay/checkout-cli login <key> writes config to ~/.vonpay/config.json.

For SDK — pass the key to the client constructor.

3. Create a session, handle the error envelope​

If anything fails, the error has a code, a fix, and a docs URL. Read fix. Retry or escalate based on what it says.

Self-diagnose without a human​

The CLI ships with a doctor command designed for agents:

vonpay checkout doctor --for-llm

Returns markdown-formatted diagnostics — API key validity, network reachability, API version, suggested next steps. Pipe the output to your agent's context when something goes wrong.

For remote agents (GitHub Actions, Vercel Edge, Lambda) without local CLI, the equivalent web endpoint is on the roadmap (GET /api/doctor).

CLAUDE.md snippet for your project​

Drop this into the CLAUDE.md at the root of your project so Claude Code understands your Von Payments integration without explanation:

## Von Payments

- API base: https://checkout.vonpay.com
- Auth: Bearer token with `vp_sk_test_*` (test) or `vp_sk_live_*` (live)
- SDKs: `@vonpay/checkout-node` (npm), `vonpay-checkout` (PyPI), both at 0.6.1
- Embedded fields: load `https://js.vonpay.com/v1/vora.js` (browser SDK)
- MCP: `@vonpay/checkout-mcp` for native tool calling
- Discovery: `GET /.well-known/vonpay.json` + `GET /llms.txt`
- Errors: every error has `code` + `fix` fields — read `fix` to self-correct
- Docs: https://docs.vonpay.com

System prompt templates​

E-commerce agent​

You are a checkout assistant for an online store powered by Von Payments.

When a customer is ready to pay:
1. Create a checkout session via POST /v1/sessions with the cart total,
   currency, and country
2. Return the checkout URL for the customer to complete payment
3. If an error occurs, read the `fix` field and retry

Auth: Use the VON_PAY_SECRET_KEY environment variable as a Bearer token.
API reference: https://checkout.vonpay.com/llms.txt

Platform / operations agent​

You are a payments operations agent for a platform using Von Payments.

Capabilities:
- Create checkout sessions for merchants
- Check session status and payment outcomes
- Capture authorized payment intents
- Issue refunds
- Monitor API health

Before making API calls, fetch
https://checkout.vonpay.com/.well-known/vonpay.json
to discover the current API version and endpoints.

When an API call fails, read the error `code` and `fix` fields to
diagnose and retry automatically. Do not ask the user for help unless
the fix field says to.

What's next​