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.llmHint + VonPayError.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://docs.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 VON_PAY_SECRET_KEY to a vp_sk_test_* key. Restart the client; tools appear.

For CLI — npx @vonpay/checkout-cli checkout 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.

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) — pin the major you tested against and read the current version from the registry, never from a docs page
- Hosted checkout: load `https://js.vonpay.com/v1/vora-hosted.js` (browser SDK, redirect drop-in)
- 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://docs.vonpay.com/llms-full.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.

Anti-patterns to avoid​

Whether you're an agent acting autonomously or a developer pairing with one, these are the failure modes that cause real payment incidents:

  • Don't fulfill on the client-side result. A submit() result or a redirect return is a UX signal, not proof of settlement. Confirm the payment_intent.succeeded / charge.succeeded webhook server-side before shipping goods or granting access.
  • Don't trust a client-supplied amount. The amount is frozen on the session at creation, server-side. Never recompute or accept a price from the browser at charge time.
  • Verify the webhook signature before acting on the payload. Treat every byte as attacker-controlled until your HMAC compare passes — see Webhook verification.
  • Don't re-charge a charge-only result. A guest charged: true submit already moved money and minted no token; charging it again double-charges. Branch error → token → charged, and on the manual wallet path never also call /v1/payment_intents.
  • Don't hardcode a payment processor. Routing is decided server-side — your integration never names or selects a gateway. Read the capability map; don't import a processor's own SDK.
  • Handle unknown webhook types gracefully. New event types ship without an SDK bump — return 200 and log; never raise on a type you don't recognize.
  • Use a stable idempotency key on writes. Key it to the checkout attempt (e.g. the cart id), not a fresh value per retry, so a retried charge never duplicates.

What's next​