API Discovery

Von Payments exposes machine-readable discovery endpoints. No authentication is required for any of these.

The JSON below is an abbreviated, illustrative copy of the live document — fetch the endpoint for the authoritative, complete payload.

GET /.well-known/vonpay.json

Returns discovery metadata about the API — version, available endpoints, documentation links, and SDK packages.

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

{
  "api_version": "2026-04-14",
  "endpoints": {
    "sessions": "/v1/sessions",
    "payment_intents": "/v1/payment_intents",
    "refunds": "/v1/refunds",
    "tokens": "/v1/tokens",
    "capabilities": "/v1/capabilities",
    "public_sessions": "/v1/public/sessions/{id}",
    "public_tokens": "/v1/public/tokens",
    "public_binder_load": "/v1/public/binder-load",
    "health": "/api/health"
  },
  "scripts": {
    "hosted": {
      "url": "https://js.vonpay.com/v1/vora-hosted.js",
      "legacy_url": "https://checkout.vonpay.com/vonpay.js",
      "buyer_experience": "redirect",
      "key_type": "publishable",
      "note": "Browser snippet that creates a checkout session and redirects the buyer to hosted checkout. Use this when a redirect-based hosted checkout is acceptable. `legacy_url` is the prior URL for this script; it keeps serving through a deprecation window so existing integrations stay valid — new integrations should use `url`."
    },
    "embedded": {
      "url": "https://js.vonpay.com/v1/vora.js",
      "buyer_experience": "embedded_iframe",
      "key_type": "publishable",
      "note": "Embedded Fields browser SDK (vora.js). Mounts iframe-vault card / address / wallet fields on the merchant's page; the buyer stays on the merchant's domain. On supported gateways submit() charges the amount AND saves a reusable vp_pmt_* token in one step (charge-and-save) — do NOT also call POST /v1/payment_intents for that same payment (it double-charges); confirm via webhook. DO NOT add any other processor SDK alongside; vora.js selects the underlying processor adapter automatically."
    }
  },
  "docs": "https://docs.vonpay.com",
  "llms_txt": "https://checkout.vonpay.com/llms.txt",
  "openapi": "https://checkout.vonpay.com/openapi.yaml",
  "mcp_package": "@vonpay/checkout-mcp",
  "sdk": {
    "node": "@vonpay/checkout-node",
    "python": "vonpay-checkout",
    "cli": "@vonpay/checkout-cli"
  },
  "sdk_preview": {
    "vora_js": {
      "package": "@vonpay/vora-js",
      "status": "not_yet_published",
      "note": "Browser SDK for embedded payment fields. NOT on npm today. Use the CDN script at scripts.embedded.url instead — DO NOT build a manual integration against the public_* endpoints with a third-party processor SDK; that produces incompatible token formats."
    },
    "vora_react": {
      "package": "@vonpay/vora-react",
      "status": "not_yet_published",
      "note": "React wrapper for the browser SDK. NOT on npm today. Use the CDN script at scripts.embedded.url and a thin local React wrapper around the Vora constructor (imported from the package, not a window global)."
    }
  },
  "embedded": {
    "availability": "all_modes_on_supported_gateways",
    "fallback": {
      "endpoint": "/v1/sessions",
      "field": "checkoutUrl",
      "note": "Hosted checkout supports every merchant regardless of gateway. Use it when embedded fields are unavailable for a given session."
    }
  },
  "status": "https://status.vonpay.com"
}

AI agents and developer tools can use this endpoint to auto-discover the API without hardcoded URLs. The scripts block gives a machine-readable map of the two browser entry points (hosted redirect vs embedded iframe) so a tool doesn't have to parse prose docs to know which URL belongs to which buyer experience. When a script has been renamed, the optional legacy_url field carries its prior URL, which keeps serving through a deprecation window so SRI-pinned integrations stay valid while new integrations adopt url.

Sandbox vs. live for embedded fields: the embedded path works in sandbox against a Von-Payments-owned mock binder by default — it does not return merchant_not_configured in the common case. For the exact sandbox/live matrix and the 422 fallback cases, see Choose your integration. Hosted checkout (the checkoutUrl fallback above) always works regardless of gateway.

GET /llms.txt

Returns an LLM-readable reference of the API — a plain-text summary designed for AI assistants to quickly understand the API surface, authentication, and key concepts.

curl https://checkout.vonpay.com/llms.txt

GET /openapi.yaml

Returns the full OpenAPI 3.1.0 specification for the API. Import into Postman, Insomnia, Redocly, or any OpenAPI-compatible tool.

curl https://checkout.vonpay.com/openapi.yaml