Developer documentation

Connect an AI agent to VotexPay: create a scoped key, connect MCP, make a user-paid purchase, follow the approval handoff and verify completion.

Current production scope

User-paid purchases work in production without PCI or an issuer. Saved Stripe card payments work in production with human approval on the Pro plan. Agent runs and Dual-LLM verification are Pro+. Vault card filling, PCI autofill, unified card entry and virtual cards are coming soon (test/preview only today). Production PCI is disabled.

Free, Pro and Business plans

Cost-bearing capabilities are plan-gated. Free is for exploration and user-paid handoffs. Pro adds agent runs, Dual-LLM verification and saved-card payments. Business adds higher limits; PCI autofill and virtual cards are coming soon.

FeatureFree (€0)Pro (€39)Business (€129)
Agent runs / Dual-LLMNo500 / month3,000 / month
Age verificationNoYesYes
Active API keys11050
Saved cards1520
User-paid purchases25 / month1,000 / month5,000 / month
Saved-card agent paymentsNoYesYes
PCI vault / autofillNoNoComing soon
Virtual cards (Issuing)NoNoComing soon
Standalone browser sessionsNoYesYes
History7 days90 days365 days

Current prices and limits: Pricing.

Manage the plan at Billing. A quota or plan failure returns 403 with an upgrade message. Limits reset monthly (UTC).

Quickstart

The fastest path is a user-paid purchase. The agent prepares the purchase and shares a one-time approval link. The user pays on the merchant site and confirms completion with the merchant order reference. VotexPay never receives card data on this rail.

1. Create an API key

Open API Keys. Use one key per agent. New keys default to the Agent safe preset; choose Read only for read-only connectors or Select all for every scope except issuing and payments:auto. See API key scopes.

2. Connect MCP or REST

Use the streamable HTTP MCP endpoint or call the REST API directly. Send the key as a bearer token. Keys are shown once and stored hashed.

3. Create a user-paid purchase

Provide amount, currency, merchant name, item description and the merchant checkout URL. No card or browser session is needed.

4. Share the approval link

The response includes a one-time handoff_url at https://votexpay.com/pay/{token}. The user opens it, approves or rejects, opens the merchant checkout, pays and confirms completion with the merchant order reference.

5. Poll status

Poll GET /api/v1/purchases/{id} until the purchase is completed, rejected, failed or expired. Do not infer success from an approval alone.

Base URL: https://api.votexpay.com
MCP:      https://api.votexpay.com/mcp
Header:   Authorization: Bearer sk_votex_...

POST /api/v1/purchases
{
  "rail": "user_paid",
  "amount": 49.0,
  "currency": "usd",
  "checkout_url": "https://shop.example/checkout/abc",
  "merchant_name": "Example Shop",
  "item_description": "Order 123"
}

Response:
{
  "purchase_id": "uuid",
  "rail": "user_paid",
  "status": "pending",
  "handoff_url": "https://votexpay.com/pay/<token>"
}
MCP client configuration (streamable HTTP)

{
  "mcpServers": {
    "votex": {
      "type": "streamable-http",
      "url": "https://api.votexpay.com/mcp",
      "headers": {
        "Authorization": "Bearer sk_votex_..."
      }
    }
  }
}

Connect Claude, Cursor or ChatGPT

The production MCP endpoint is https://api.votexpay.com/mcp. OAuth is recommended for multi-user connectors; use an API key only for clients that do not support OAuth.

ChatGPT

  1. Enable developer/connector mode and add a remote MCP connector.
  2. Set the URL to https://api.votexpay.com/mcpand choose OAuth/DCR.
  3. Sign in to VotexPay, review scopes and approve.
  4. Call votex_whoami; expectauth_type: oauth.

Claude

  1. Add a remote MCP connector athttps://api.votexpay.com/mcp.
  2. Start OAuth in the browser and review VotexPay consent.
  3. Call votex_whoami to verify the connection and scopes.

Cursor

  1. Add a Streamable HTTP MCP server in Cursor settings.
  2. Use https://api.votexpay.com/mcpand choose OAuth/DCR.
  3. Complete VotexPay consent; loopback callbacks are allowed.

API-key fallback

Create a dedicated key in API Keys and send it as Authorization: Bearer sk_votex_.... Choose Read only or Agent safe; do not put the key in prompts or browser code.

Common connection errors

401 means the token is missing, expired or revoked. invalid_redirect_uri means the callback is not allowlisted or does not exactly match the registration. Missing-scope errors require reconnecting with the requested permission. Payments remain pending unless an explicitly granted payments:auto scope and the user's policy allow auto-confirmation.

API key scopes and presets

Create keys at API Keys. The Permissions selector has one checkbox per scope and three presets. Keys are scoped at creation and cannot be edited later; revoke a key and create a new one to change its permissions. The create button is disabled when no scopes are selected.

PresetScopes
Read onlycards:read, payments:read, agent:read
Agent safe (new-key default)cards:read, payments:read, payments:write, browser, purchases, agent:read, agent:run, billing:write, link
Select allEvery scope except issuing and payments:auto
ScopeWhat it allows
cards:readView saved cards and masked metadata.
payments:readView payments and status.
payments:writeCreate payment requests and start payment flows. Payments stay pending for human approval unless the credential also has payments:auto.
payments:autoConfirm payments on saved cards without a per-payment approval, within your VotexPay policy and threshold. High trust; unchecked by default.
browserOpen isolated browser sessions and run browser actions.
purchasesCreate and manage purchase requests and handoffs.
agent:readView agent runs and their results.
agent:runStart and control agent runs (Pro+ plan required).
billing:writeCreate a Stripe Checkout/portal link to upgrade. No charge by itself.
issuingLegacy reserved scope. OAuth does not advertise it; virtual cards are coming soon.

API keys created without scopes use the agent-safe preset. OAuth authorization requests without a scope also default to the Agent safe preset. Write and run scopes, including payments:auto, must be requested explicitly and are shown on the consent screen.

issuing is a legacy reserved scope for API keys. OAuth does not advertise it while virtual cards are coming soon. There is no * checkbox. Legacy keys that already carry * show a Full access badge.

API: POST /api/v1/keys accepts { name, scopes?: string[] } with a Supabase JWT and step-up. Omitting scopes applies the agent-safe default. An unknown scope returns 400. A call missing a required scope returns 403 API key missing scope: ....

ChatGPT and MCP clients

Create a dedicated key for each client with only the scopes it needs. ChatGPT cannot change a key's scopes. Use Read only for read-only or Pro connectors and Agent safe for full agent actions. Never paste a key into a description, prompt or chat message.

Architecture

The API and MCP server are the control plane. Supabase handles identity and data, Stripe handles saved-card payments, and an isolated browser handles explicit web actions. The payment rails below the control plane have different availability.

User

Controls approvals, step-up authentication, trusted devices and payment limits.

External agent

Connects over MCP or REST with a scoped API key. Can browse, research and request actions.

VotexPay API and MCP

Approval and completion layer. Validates keys, binds approvals, runs agent jobs and exposes one-time payment handoffs.

Supabase

Auth, Postgres, row-level security

Stripe

Saved-card payments, 3DS, webhooks

Isolated browser

Sessions, actions, screenshots

Policy and audit

Scopes, approvals, request IDs

Payment rails

User-paid handoffLiveVault card fillComing soonSupplier APIComing soonLink US/CanadaLiveVirtual cardsComing soon
VotexPay never places raw card data in agent context. User-paid purchases complete on the merchant site; vault card filling is available only in test/preview today.

Purchase flow

User-paid purchases are the production path that works without PCI. The agent creates the purchase, the user approves through a one-time handoff, pays on the merchant site and confirms completion with the merchant order reference.

  1. 01

    Create purchase

    The agent sends amount, currency, merchant and checkout URL with rail user_paid.

    POST /api/v1/purchases

  2. 02

    User opens handoff

    The one-time /pay/{token} link shows the merchant, amount and item before approval.

    GET /api/v1/handoffs/{token}

  3. 03

    Approve or reject

    The user decides with a verified session. Rejection or expiry ends the flow.

    POST /api/v1/handoffs/{token}/approve

  4. 04

    Pay on merchant site

    The user opens the merchant checkout in their own browser. VotexPay does not see card data.

    Merchant checkout

  5. 05

    Confirm and poll

    The user confirms completion with a required merchant order reference. The agent polls until the purchase is completed. verification_status is user_confirmed by default and becomes merchant_verified only after an operator checks the receipt/order.

    GET /api/v1/purchases/{id}

Approval is not payment. Completion requires the user to pay on the merchant site and confirm. Agents must poll status and must not claim a merchant order succeeded without it.

Vault purchase flow is coming soon

Vault purchases use a Basis Theory test vault, fill card fields in an isolated session and submit the checkout. Production returns 503 PCI vault is disabled until a live vault is configured. Merchant CAPTCHAs and 3DS may require user handoff.

Rail comparison

Rails differ in who pays, who sees card data and whether the rail is available today.

User-paid

Live

Agent creates a purchase; user pays on the merchant site.

Works in production. No PCI or issuer required. VotexPay does not receive card data.

Vault card fill

Coming soon

Agent fills and submits an approved card in an isolated browser.

Basis Theory test vault only. Production PCI is disabled.

Supplier API

Coming soon

Reseller and supplier integration for direct order placement.

Planned. Not built.

Link US/Canada

Live

Link rail for eligible US and Canada Link accounts.

Live. The user approves every spend in Link. Not available for EU/PT wallets.

Virtual cards

Coming soon

Issued single-use cards for merchant payments.

Coming soon. Stripe Issuing was refused. Nium and Marqeta are not integrated.

A rail is not a guarantee. Merchant acceptance, CAPTCHA, 3DS and order completion remain outside VotexPay control.

API, MCP and SDKs

Use MCP for goal-based agents and REST for explicit control. Both accept the same scoped API key. User-only actions such as approve, reject and user-paid completion require a Supabase JWT and step-up.

SurfaceUse it forCurrent status
MCP (streamable HTTP)Tool discovery, agent runs, purchases, payments, browser actionsLive
REST APIExplicit requests, status polling and integrationsLive
Python SDKvotex-sdk clients for cards, payments, browser and purchasesLive
TypeScript SDK@votex/sdk clients for the same API surfaceLive
MCP tools by job
Discover:  votex_whoami, votex_upgrade_plan, votex_list_cards, votex_payment_policy
Browse:    votex_run_agent, votex_get_status, votex_navigate, votex_extract,
           votex_open_browser, votex_browser_action, votex_screenshot
Purchase:  votex_create_purchase, votex_get_purchase
Pay:       votex_request_payment, votex_list_payments, votex_get_payment
Vault:     votex_fill_card, votex_submit_purchase (test only)
REST endpoints (API key friendly)
GET    /api/v1/vault/cards
POST   /api/v1/purchases
POST   /api/v1/purchases/{id}/handoff
GET    /api/v1/purchases
GET    /api/v1/purchases/{id}
GET    /api/v1/handoffs/{token}
POST   /api/v1/payments
GET    /api/v1/payments
GET    /api/v1/payments/{id}
POST   /api/v1/actions
POST   /api/v1/browser/sessions
POST   /api/v1/browser/sessions/{id}/actions
DELETE /api/v1/browser/sessions/{id}

User-only (JWT and step-up):
POST   /api/v1/purchases/{id}/approve|reject
POST   /api/v1/purchases/{id}/user-paid/complete
POST   /api/v1/handoffs/{token}/approve|reject
POST   /api/v1/payments/{id}/approve|reject
# Python
from votex import VotexClient

with VotexClient("sk_votex_...") as client:
    cards = client.cards.list()
    payment = client.payments.create(cards[0]["id"], 12.5)

// TypeScript
import { VotexClient } from "@votex/sdk";

const client = new VotexClient("sk_votex_...");
const cards = await client.cards.list();

The full tool reference, parameter shapes and examples are in the AI docs.

Security and trust

VotexPay is built around approval binding and data separation. These are engineering controls, not certification claims.

01Identity and step-up

Supabase auth, TOTP, passkeys and trusted devices protect approval decisions.

02Scoped access

Hashed, revocable API keys limit agents to the scopes they need.

03Approval binding

Purchase approvals bind amount, merchant origin, card and session where applicable.

04Execution guardrails

SSRF DNS checks, prompt-injection filtering, request IDs and screenshot blocking after card fill.

05Data separation

RLS in Postgres, test and production Supabase separation, and no PAN in the VotexPay database.

Defense in depth, not a certification claim. VotexPay does not assert PCI DSS or SOC 2 certification on these pages.
  • API keys are hashed at rest and revocable; scopes are checked per tool.
  • TOTP, passkeys and trusted devices protect sensitive user decisions.
  • Row-level security and ownership checks protect runs, sessions and purchases.
  • SSRF DNS checks block localhost, private networks and non-HTTP(S) URLs.
  • Screenshot capture is blocked after card fill in a session.
  • Request IDs and CORS rules make traffic traceable and limit browser origins.
  • Test and production Supabase projects are separated.

Limits and status

What agents cannot do today

Agents cannot execute real merchant payments through Agent Runs, approve their own payments, use virtual cards, or rely on production card autofill. Link Agent Wallet spends always need the user's approval in Link. Supplier rails are not built.
  • Agent Runs browse and research. They do not complete merchant checkout.
  • Production PCI is disabled. Vault fill, autofill and unified card entry are test only.
  • User-paid purchases are paid by the user on the merchant site. VotexPay does not charge for those.
  • votex_request_payment charges a saved Stripe card to VotexPay. It is not a merchant checkout.
  • Merchant CAPTCHA, 3DS and checkout changes may require user handoff and are not guaranteed.
  • Amounts are in major units of the supplied currency. There is no FX conversion.
  • Browser sessions are in-memory and user-scoped. Close them when done.
  • On error, surface the message to the user. Do not retry blindly.

AI docs and llms.txt

Machine-readable context for agents lives at https://votexpay.com/llms.txt. The structured agent guide, tool map and status are at /ai-docs.

https://votexpay.com/docs
https://votexpay.com/ai-docs
https://votexpay.com/llms.txt