Documentation for AI agents
How agents should use the VotexPay MCP server and REST API: current capability status, purchase flow, tool map, approval rules, region gating and honest limits.
Read this before you call a tool
Start here
Machine-readable file: https://votexpay.com/llms.txt. Human docs: /docs.
MCP endpoint (streamable HTTP): https://api.votexpay.com/mcp
REST base URL: https://api.votexpay.com
Auth header: Authorization: Bearer sk_votex_...
Test deployment (vault purchases and autofill):
https://votex-test-43ec.up.railway.appThe user creates the API key at /keys. Keys are secrets, shown once, stored hashed and revocable. One key per agent. Never expose a key client-side.
New keys default to the Agent safe preset. Existing keys may still carry full access (*). A missing scope returns 403 API key missing scope: .... See API key scopes below.
API key scopes and presets
The user creates keys at /keys. The Permissions selector has one checkbox per scope and three presets. Keys are scoped at creation and cannot be edited; to change permissions, revoke the key and create a new one. 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. |
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 or plan change until payment. |
issuing | Legacy reserved scope for API keys. OAuth does not advertise it; virtual cards are coming soon. |
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
MCP URL: https://api.votexpay.com/mcp. Prefer OAuth/DCR for multi-user clients. Without an explicit scope, OAuth grants Agent safe; Read only and Full are also available.
- ChatGPT: add a remote connector in developer mode, enter the MCP URL, choose OAuth/DCR and approve VotexPay consent.
- Claude: add a remote MCP connector at the same URL, complete browser OAuth, then test
votex_whoami. - Cursor: add a Streamable HTTP MCP server, select OAuth/DCR and complete consent (loopback callbacks are allowed).
- API-key fallback: use a dedicated key as
Authorization: Bearer sk_votex_...; never put it in a prompt or browser code.
Test with votex_whoami. Common errors: 401 means missing/expired auth; invalid_redirect_uri means the callback must match the client registration; a missing scope requires reconnecting. Payments need payments:write and auto-confirmation additionally needs payments:auto.
Free, Pro and Business plans
Capability status
Use this matrix to choose a safe path. A live feature is available in production. A test feature requires the test or preview deployment.
| Capability | Status | Current scope |
|---|---|---|
| MCP, REST and SDKs | Live | Streamable HTTP MCP, REST endpoints and Python/TypeScript SDKs. |
| User-paid purchase handoff | Live | Works in production without PCI or an issuer. The user pays on the merchant site. |
| Saved-card payments | Live | Stripe charge to VotexPay with human approval, 3DS and webhooks. Not a merchant checkout. |
| Agent Runs | Live | Pro+ only. Dual-LLM browsing and research with a quarantined extractor. No real merchant payments. |
| Age verification | Live | Pro/Business only. Stripe Identity document + selfie verification; verified badge near the email. VotexPay stores status/dates and session/report IDs, not documents, selfies, DOB or address. |
| Browser sessions and actions | Live | Navigate, click, type, wait, scroll, press, select, extract and screenshot in isolated sessions. |
| Vault purchase, fill and submit | Coming soon | Coming soon. Basis Theory test vault. Production returns 503 PCI vault is disabled. |
| PCI autofill and unified card entry | Coming soon | Coming soon. Test/preview only. Production PCI is disabled. |
| Stripe Elements iframe filling and select | Coming soon | Test only. CAPTCHA and 3DS may require user handoff. |
| Link rail for US/Canada | Live | Live for eligible US/Canada Link wallets. The user connects Link in Settings and approves every spend in Link; VotexPay fills the one-time card server-side. |
| Supplier API rail | Coming soon | Reseller and supplier integration is planned but not built. |
| Stripe SPT and Forwarding | Coming soon | Pending. Not available today. |
| Virtual cards | Coming soon | Coming soon. Stripe Issuing was refused. Nium and Marqeta are not integrated. |
| Production card autofill | Coming soon | Coming soon. Production PCI is disabled. Arbitrary-merchant autonomous card purchases are not offered. |
| ChatGPT and Claude plugins | Coming soon | Planned for later. Use MCP or REST today. |
MCP, REST and SDKs
LiveStreamable HTTP MCP, REST endpoints and Python/TypeScript SDKs.
User-paid purchase handoff
LiveWorks in production without PCI or an issuer. The user pays on the merchant site.
Saved-card payments
LiveStripe charge to VotexPay with human approval, 3DS and webhooks. Not a merchant checkout.
Agent Runs
LivePro+ only. Dual-LLM browsing and research with a quarantined extractor. No real merchant payments.
Age verification
LivePro/Business only. Stripe Identity document + selfie verification; verified badge near the email. VotexPay stores status/dates and session/report IDs, not documents, selfies, DOB or address.
Browser sessions and actions
LiveNavigate, click, type, wait, scroll, press, select, extract and screenshot in isolated sessions.
Vault purchase, fill and submit
Coming soonComing soon. Basis Theory test vault. Production returns 503 PCI vault is disabled.
PCI autofill and unified card entry
Coming soonComing soon. Test/preview only. Production PCI is disabled.
Stripe Elements iframe filling and select
Coming soonTest only. CAPTCHA and 3DS may require user handoff.
Link rail for US/Canada
LiveLive for eligible US/Canada Link wallets. The user connects Link in Settings and approves every spend in Link; VotexPay fills the one-time card server-side.
Supplier API rail
Coming soonReseller and supplier integration is planned but not built.
Stripe SPT and Forwarding
Coming soonPending. Not available today.
Virtual cards
Coming soonComing soon. Stripe Issuing was refused. Nium and Marqeta are not integrated.
Production card autofill
Coming soonComing soon. Production PCI is disabled. Arbitrary-merchant autonomous card purchases are not offered.
ChatGPT and Claude plugins
Coming soonPlanned for later. Use MCP or REST today.
Agent tool map
Start with the smallest tool that answers the question. Prefer status reads over writes, and prefer the user-paid rail when PCI is not available.
Agent through MCP or REST
Scoped API key. One key per agent. Revocable at any time.
Discover
Confirm the key, scopes, cards and payment policy before acting.
votex_whoamivotex_list_cardsvotex_payment_policyBrowse and research
Run a goal, or drive a session with explicit browser actions.
votex_run_agentvotex_navigatevotex_extractvotex_open_browservotex_browser_actionBuy on the user-paid rail
Create a purchase with a merchant checkout URL and share the handoff.
votex_create_purchasevotex_get_purchasePay from a saved card
Request a card payment to VotexPay. The user approves, then you poll.
votex_request_paymentvotex_get_paymentFill a vault checkout
Test/preview only. Fill and submit an approved card in a session.
votex_fill_cardvotex_submit_purchasevotex_get_purchaseVerify and report
Poll status, surface errors, and never claim success without a status.
votex_get_statusvotex_list_runsvotex_get_paymentPurchase flow
A purchase is a request for approval, not a guaranteed order. The user sees the purchase ID, linked Agent Run and agent/API key name, the merchant, amount, item, rail and status, then decides. Completion requires a separate user action on the merchant site. The approval page never shows card data.
- 01
Create
Call votex_create_purchase. Use rail user_paid for production.
votex_create_purchase
- 02
Hand off
Share the one-time /pay/{token} link returned as handoff_url.
POST /api/v1/purchases/{id}/handoff
- 03
User decides
The user approves or rejects with a verified session. Agents cannot decide.
POST /api/v1/handoffs/{token}/approve
- 04
User pays
The user opens the merchant checkout and pays. VotexPay does not charge on this rail.
Merchant checkout
- 05
Verify
The user confirms completion; the agent polls until completed.
votex_get_purchase
Human-in-the-loop
votex_request_paymentcreates a payment with statuspending.- The user approves or rejects it in the VotexPay app (for example
/vaultthen Payment approvals). - Poll
votex_get_paymentuntilconfirmedorfailed.
Agents cannot approve payments. If the user disabled approval or set a threshold covering the amount, the payment may be confirmed immediately. Never claim a charge succeeded without checking the status.
A goal-based run (votex_run_agent) may pause with awaiting_approval when its plan reaches a payment step. The user approves, then the run resumes. The run itself does not execute a merchant payment.
User-paid purchase flow (production)
votex_create_purchasewithrail: "user_paid", a merchantcheckout_url, amount, currency, merchant and item. No card or browser session is needed. Optionally passrun_idto link the Agent Run that requested the purchase; it must belong to the user or the call fails withAgent run not found.- Share the returned
handoff_url(https://votexpay.com/pay/{token}) with the user.POST /api/v1/purchases/{id}/handoffrotates it. - The user opens
/pay/{token}(or clicks Review & approve on the Dashboard or Agent Runs), approves in the focused handoff sheet, is redirected to the merchant checkout, pays, then confirms completion with the merchant order reference. - Poll
votex_get_purchaseorvotex_list_purchasesuntilcompleted. Completed means user-confirmed by default. `verification_status` becomes `merchant_verified` only after an operator checks the receipt/order. - If the URL or amount is wrong before payment, call
votex_cancel_purchase. Duplicate active purchases for the same merchant, amount and currency within 15 minutes are refused.
VotexPay never sees card data on this rail. The user must verify the merchant, amount and origin before paying. Confirmation calls POST /api/v1/purchases/{id}/user-paid/complete and requires step-up.
Vault purchase flow (test only)
votex_list_cardsthen choose a card withpci_card_id.votex_open_browserthen navigate to the merchant checkout.votex_create_purchasewithrail: "vault"(must be set explicitly; the default is user_paid), card, session, amount, currency, merchant and item.- The user approves in
/vaultthen Purchase approvals, or through the returned/pay/{token}handoff. votex_fill_cardwith the purchase and checkout selectors.votex_submit_purchasewith the submit selector and a success criterion.- Poll
votex_get_purchaseuntilcompleted.
The approval binds amount, merchant origin, card and session. VotexPay does not scrape the merchant total automatically. The user must verify the amount on the checkout page before approving. Screenshots are disabled after fill_card.
Production response for vault tools
503 PCI vault is disabled for vault purchases and autofill until a live Basis Theory vault is configured. Use the test deployment only for evaluation.Tool reference
The full MCP tool list with current status. A tool that exists in the server does not imply that its downstream rail is available.
votex_whoami
Liveparams: None
Verify the API key and return plan, features, limits and scopes. Use it first so you know whether agent runs/Dual-LLM (Pro+) are available. User-paid purchases work on Free.
votex_upgrade_plan
Liveparams: target_plan ('pro' or 'business')
Create a Stripe Checkout or billing portal link. Requires billing:write. Does not change the plan or charge until the user pays in Stripe.
votex_run_agent
Liveparams: goal (required), url (optional)
Pro+ only. Queue a goal-based browsing/research run. Returns run_id; poll status. Do not use for a direct user-paid purchase; use votex_create_purchase. Pauses at payment steps. It does not execute merchant payments.
votex_get_status
Liveparams: run_id (required)
Status and results. Statuses: pending|running|awaiting_approval|completed|failed|cancelled.
votex_list_runs
Liveparams: None
Recent runs (up to 20) with status and source.
votex_list_cards
Liveparams: None
Masked cards [{id,pci_card_id,last4,brand,created_at}]. id is used for payments; pci_card_id is used for purchases and autofill.
votex_create_purchase
user_paid live; vault testLiveparams: amount, rail?, card_id?, session_id?, checkout_url?, currency?, merchant_name?, item_description?, run_id?
Create a purchase directly on rail vault or user_paid (user_paid works on Free and needs no Agent Run). user_paid needs checkout_url and returns absolute handoff_url (https://votexpay.com/pay/{token}). vault needs card_id and session_id and is test only. run_id optionally links an Agent Run that must belong to the user; the response includes agent_run_id and agent_name.
votex_get_purchase
Liveparams: purchase_id (required)
Purchase status: pending|awaiting_payment|approved|rejected|filled|completed|failed|expired. Includes rail, checkout_url and order_reference.
votex_fill_card
Coming soonparams: purchase_id, session_id, card_id, selectors, expiry_format?
Fill an approved purchase card. PAN and CVC are never returned. Requires a test PCI vault.
votex_submit_purchase
Coming soonparams: purchase_id, session_id, selector, success_selector|success_text|success_url_contains?, wait_ms?
Submit and verify a filled vault purchase. Returns completed or submitted unverified. Test only.
votex_request_payment
Liveparams: card_id (required), amount (required), currency (optional)
Create a payment that charges a saved Stripe card to VotexPay. Human-approved by default (status pending). This is not a merchant checkout.
votex_payment_policy
Liveparams: None
Read the human-in-the-loop policy: require_approval and threshold.
votex_list_payments
Liveparams: None
Recent payments (up to 20) with status.
votex_get_payment
Liveparams: payment_id (required)
Payment status: pending|confirmed|succeeded|failed|canceled|rejected.
votex_navigate
Liveparams: url (required)
One-shot navigate. Returns sanitized text. SSRF-blocked URLs are rejected.
votex_extract
Liveparams: url (required), data_needed (optional)
One-shot navigate and structured extraction with the quarantined extractor.
votex_open_browser
Liveparams: None
Open a persistent isolated session. Returns session_id.
votex_browser_action
Liveparams: session_id, action_type, params
navigate|click|type|select|wait|scroll|press|extract in a session. Use votex_fill_form for multi-field forms.
votex_fill_form
Liveparams: session_id, fields[], submit_selector?, wait_after_ms?
Fill multiple fields by selector/label/placeholder/role. Kinds: text, select, checkbox, radio. File uploads are not supported. Values are not returned. Pro+ only.
votex_screenshot
Liveparams: session_id (required)
PNG screenshot of the current page. Screenshots are blocked after card fill in that session.
votex_close_browser
Liveparams: session_id (required)
Close the session.
votex_link_status
Liveparams: None
Requires the link scope. Whether the user connected a Link Agent Wallet (US/Canada). If not, ask them to connect it in VotexPay Settings.
votex_link_payment_methods
Liveparams: None
Masked Link payment methods eligible for agent spending.
votex_link_request_spend
Liveparams: amount (minor units), currency, merchant_name, merchant_url, context (>=100 chars), payment_method_id?
Creates a Link spend request and returns approval_url. Send it to the user; only the user can approve in Link.
votex_link_get_spend
Liveparams: spend_request_id
Poll until status is 'approved'. Returns masked card brand/last4 only.
votex_link_fill_card
Liveparams: spend_request_id, session_id, selectors {number, expiry, cvc?, name?}, expiry_format?
Fills the approved one-time card into the checkout open in a VotexPay browser session on the approved merchant. PAN/CVC never reach the agent. Then click pay with votex_browser_action.
votex_issue_virtual_card
Not offeredComing soonparams: limit_amount (required), currency?, single_use?, merchant?
Legacy metadata-only tool. Stripe Issuing was refused and no issuer is integrated. Do not rely on this tool.
votex_list_virtual_cards
Not offeredComing soonparams: None
Legacy metadata-only tool. Virtual cards are coming soon; issuing is disabled.
votex_freeze_virtual_card
Not offeredComing soonparams: card_id (required), frozen?
Legacy metadata-only tool. Virtual cards are coming soon; issuing is disabled.
What agents can and cannot do today
Can
- Verify a key, list masked cards and read the payment policy.
- Run goal-based browsing and research, then read structured results.
- Open isolated sessions and run explicit browser actions.
- Create a user-paid purchase and share the approval handoff.
- Request a saved-card payment that waits for human approval.
- Poll payment, purchase and run status and report the real outcome.
- Use vault fill and submit in the test environment only.
Cannot
- Approve payments or purchases, or bypass step-up.
- See PAN or CVC, or access raw card data in agent context.
- Execute a real merchant payment through Agent Runs.
- Use virtual cards or a supplier rail today, or approve their own Link spend.
- Rely on production card autofill or arbitrary-merchant autonomous purchases.
- Guarantee merchant acceptance, CAPTCHA completion or 3DS success.
- Charge the user for a user-paid purchase. The user pays the merchant.
Region gating for Link
Link Agent Wallet is available for eligible US/Canada Link wallets. Call votex_link_status first; if the user is not connected, ask them to connect Link in VotexPay Settings.
- Only offer Link when votex_link_status returns connected:true.
- Do not infer Link eligibility from the user's country or currency.
- User-paid purchases still depend on the merchant accepting the user's payment method.
- Virtual cards are coming soon in every region.
Rules and honest limits
- Agents cannot approve payments or bypass approval.
- Cards are tokenized by Stripe; only brand and last4 are exposed.
user_paidworks without PCI or an issuer. Vault purchases,fill_cardand autofill require a test PCI vault and return 503 in production until configured.- Browser actions:
navigate, click, type, wait, scroll, press, select, extract. No file upload or download. votex_screenshotis available, but screenshots are disabled afterfill_cardfor that session.localhost, private/internal IPs and non-HTTP(S) URLs are blocked.- Sessions are in-memory and user-scoped. Close them when done. Queued runs are durable.
- Amounts are in major units of the given currency (default
usd). There is no FX conversion. - On error, surface the message to the user. Do not retry blindly.
Examples
Request a payment
1. votex_list_cards -> { cards: [{ id, pci_card_id, last4, brand }] }
2. votex_request_payment { card_id: id, amount: 12.5, currency: "usd" }
-> { payment_id, status: "pending", ... }
3. (user approves in the app)
4. votex_get_payment { payment_id } -> { status: "confirmed" }User-paid purchase (works without PCI)
1. votex_create_purchase { rail: "user_paid", amount: 49.0, currency: "usd",
checkout_url: "https://shop.example/checkout/abc",
merchant_name, item_description, run_id? }
-> { purchase_id, rail: "user_paid", status: "pending",
agent_run_id, agent_name, handoff_url: "https://votexpay.com/pay/<token>" }
2. (share handoff_url; user opens /pay/<token>, approves, pays, confirms)
3. votex_get_purchase { purchase_id } -> { status: "completed" }Vault purchase (test only)
1. votex_create_purchase { rail: "vault", card_id: pci_card_id, session_id,
amount, currency, merchant_name, item_description,
run_id? }
-> { purchase_id, rail: "vault", status: "pending", agent_run_id, agent_name }
2. (user approves in /vault -> Purchase approvals or /pay/<token>)
3. votex_fill_card { purchase_id, session_id, card_id: pci_card_id, selectors }
4. votex_submit_purchase { purchase_id, session_id, selector, success_text }
5. votex_get_purchase { purchase_id } -> { status: "completed" }Run a task and poll
votex_run_agent { goal: "Open https://example.com and report the title" }
-> { run_id, status: "pending" }
votex_get_status { run_id } # poll every few seconds
-> { status: "completed", extracted_data: { ... } }Navigate and extract
votex_navigate { url: "https://example.com" }
votex_extract { url: "https://example.com", data_needed: ["title"] }Multi-step browser session
votex_open_browser -> { session_id }
votex_browser_action { session_id, action_type: "navigate", params: { url: "https://example.com" } }
votex_browser_action { session_id, action_type: "click", params: { selector: "a" } }
votex_browser_action { session_id, action_type: "extract", params: { data_needed: ["title"] } }
votex_close_browser { session_id }