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
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.
| Feature | Free (€0) | Pro (€39) | Business (€129) |
|---|---|---|---|
| Agent runs / Dual-LLM | No | 500 / month | 3,000 / month |
| Age verification | No | Yes | Yes |
| Active API keys | 1 | 10 | 50 |
| Saved cards | 1 | 5 | 20 |
| User-paid purchases | 25 / month | 1,000 / month | 5,000 / month |
| Saved-card agent payments | No | Yes | Yes |
| PCI vault / autofill | No | No | Coming soon |
| Virtual cards (Issuing) | No | No | Coming soon |
| Standalone browser sessions | No | Yes | Yes |
| History | 7 days | 90 days | 365 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
- Enable developer/connector mode and add a remote MCP connector.
- Set the URL to
https://api.votexpay.com/mcpand choose OAuth/DCR. - Sign in to VotexPay, review scopes and approve.
- Call
votex_whoami; expectauth_type: oauth.
Claude
- Add a remote MCP connector at
https://api.votexpay.com/mcp. - Start OAuth in the browser and review VotexPay consent.
- Call
votex_whoamito verify the connection and scopes.
Cursor
- Add a Streamable HTTP MCP server in Cursor settings.
- Use
https://api.votexpay.com/mcpand choose OAuth/DCR. - 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.
| Preset | Scopes |
|---|---|
| Read only | cards: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 all | Every scope except issuing and payments:auto |
| Scope | What it allows |
|---|---|
cards:read | View saved cards and masked metadata. |
payments:read | View payments and status. |
payments:write | Create payment requests and start payment flows. Payments stay pending for human approval unless the credential also has payments:auto. |
payments:auto | Confirm payments on saved cards without a per-payment approval, within your VotexPay policy and threshold. High trust; unchecked by default. |
browser | Open isolated browser sessions and run browser actions. |
purchases | Create and manage purchase requests and handoffs. |
agent:read | View agent runs and their results. |
agent:run | Start and control agent runs (Pro+ plan required). |
billing:write | Create a Stripe Checkout/portal link to upgrade. No charge by itself. |
issuing | Legacy 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
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
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.
- 01
Create purchase
The agent sends amount, currency, merchant and checkout URL with rail user_paid.
POST /api/v1/purchases
- 02
User opens handoff
The one-time /pay/{token} link shows the merchant, amount and item before approval.
GET /api/v1/handoffs/{token}
- 03
Approve or reject
The user decides with a verified session. Rejection or expiry ends the flow.
POST /api/v1/handoffs/{token}/approve
- 04
Pay on merchant site
The user opens the merchant checkout in their own browser. VotexPay does not see card data.
Merchant checkout
- 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}
Vault purchase flow is coming soon
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
LiveAgent 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 soonAgent fills and submits an approved card in an isolated browser.
Basis Theory test vault only. Production PCI is disabled.
Supplier API
Coming soonReseller and supplier integration for direct order placement.
Planned. Not built.
Link US/Canada
LiveLink 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 soonIssued single-use cards for merchant payments.
Coming soon. Stripe Issuing was refused. Nium and Marqeta are not integrated.
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.
| Surface | Use it for | Current status |
|---|---|---|
| MCP (streamable HTTP) | Tool discovery, agent runs, purchases, payments, browser actions | Live |
| REST API | Explicit requests, status polling and integrations | Live |
| Python SDK | votex-sdk clients for cards, payments, browser and purchases | Live |
| TypeScript SDK | @votex/sdk clients for the same API surface | Live |
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.
- 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
- 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_paymentcharges 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