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

Agents cannot approve payments or purchases. Agent Runs browse and research; they do not execute real merchant payments. User-paid purchases are paid by the user on the merchant site. Vault card filling is test only. Virtual cards and production autofill are coming soon.

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.app

The 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.

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.
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 or plan change until payment.
issuingLegacy 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

Free includes user-paid handoffs; agent runs, Dual-LLM, browser sessions, saved-card payments and age verification require Pro or Business. Current prices and limits are on votexpay.com/pricing. OAuth defaults to Agent safe; read-only and full scopes are also available. Auto-charging saved cards requires the separate payments:auto scope. Plan or quota failures are returned as tool errors with an upgrade message.

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.

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.

Status as of 19 November 2026. This page does not promise roadmap dates. If a tool is coming soon or not live, do not simulate it or claim it succeeded.

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_policy

Browse and research

Run a goal, or drive a session with explicit browser actions.

votex_run_agentvotex_navigatevotex_extractvotex_open_browservotex_browser_action

Buy on the user-paid rail

Create a purchase with a merchant checkout URL and share the handoff.

votex_create_purchasevotex_get_purchase

Pay from a saved card

Request a card payment to VotexPay. The user approves, then you poll.

votex_request_paymentvotex_get_payment

Fill a vault checkout

Test/preview only. Fill and submit an approved card in a session.

votex_fill_cardvotex_submit_purchasevotex_get_purchase

Verify and report

Poll status, surface errors, and never claim success without a status.

votex_get_statusvotex_list_runsvotex_get_payment
Agent Runs browse and research. They do not execute real merchant payments. Purchases use a separate approval and handoff flow.

Purchase 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.

  1. 01

    Create

    Call votex_create_purchase. Use rail user_paid for production.

    votex_create_purchase

  2. 02

    Hand off

    Share the one-time /pay/{token} link returned as handoff_url.

    POST /api/v1/purchases/{id}/handoff

  3. 03

    User decides

    The user approves or rejects with a verified session. Agents cannot decide.

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

  4. 04

    User pays

    The user opens the merchant checkout and pays. VotexPay does not charge on this rail.

    Merchant checkout

  5. 05

    Verify

    The user confirms completion; the agent polls until completed.

    votex_get_purchase

If the user rejects, the purchase expires, or the merchant checkout fails, report that outcome. Do not retry a purchase or create a duplicate without user direction.

Human-in-the-loop

  1. votex_request_payment creates a payment with status pending.
  2. The user approves or rejects it in the VotexPay app (for example /vault then Payment approvals).
  3. Poll votex_get_payment until confirmed or failed.

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)

  1. votex_create_purchase with rail: "user_paid", a merchant checkout_url, amount, currency, merchant and item. No card or browser session is needed. Optionally pass run_id to link the Agent Run that requested the purchase; it must belong to the user or the call fails with Agent run not found.
  2. Share the returned handoff_url (https://votexpay.com/pay/{token}) with the user. POST /api/v1/purchases/{id}/handoff rotates it.
  3. 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.
  4. Poll votex_get_purchase or votex_list_purchases until completed. Completed means user-confirmed by default. `verification_status` becomes `merchant_verified` only after an operator checks the receipt/order.
  5. 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)

  1. votex_list_cards then choose a card with pci_card_id.
  2. votex_open_browser then navigate to the merchant checkout.
  3. votex_create_purchase with rail: "vault" (must be set explicitly; the default is user_paid), card, session, amount, currency, merchant and item.
  4. The user approves in /vault then Purchase approvals, or through the returned /pay/{token} handoff.
  5. votex_fill_card with the purchase and checkout selectors.
  6. votex_submit_purchase with the submit selector and a success criterion.
  7. Poll votex_get_purchase until completed.

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

Production returns 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

    Live

    params: 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

    Live

    params: 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

    Live

    params: 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

    Live

    params: run_id (required)

    Status and results. Statuses: pending|running|awaiting_approval|completed|failed|cancelled.

  • votex_list_runs

    Live

    params: None

    Recent runs (up to 20) with status and source.

  • votex_list_cards

    Live

    params: 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 testLive

    params: 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

    Live

    params: 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 soon

    params: 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 soon

    params: 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

    Live

    params: 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

    Live

    params: None

    Read the human-in-the-loop policy: require_approval and threshold.

  • votex_list_payments

    Live

    params: None

    Recent payments (up to 20) with status.

  • votex_get_payment

    Live

    params: payment_id (required)

    Payment status: pending|confirmed|succeeded|failed|canceled|rejected.

  • votex_navigate

    Live

    params: url (required)

    One-shot navigate. Returns sanitized text. SSRF-blocked URLs are rejected.

  • votex_extract

    Live

    params: url (required), data_needed (optional)

    One-shot navigate and structured extraction with the quarantined extractor.

  • votex_open_browser

    Live

    params: None

    Open a persistent isolated session. Returns session_id.

  • votex_browser_action

    Live

    params: 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

    Live

    params: 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

    Live

    params: session_id (required)

    PNG screenshot of the current page. Screenshots are blocked after card fill in that session.

  • votex_close_browser

    Live

    params: session_id (required)

    Close the session.

  • votex_link_status

    Live

    params: 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

    Live

    params: None

    Masked Link payment methods eligible for agent spending.

  • votex_link_request_spend

    Live

    params: 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

    Live

    params: spend_request_id

    Poll until status is 'approved'. Returns masked card brand/last4 only.

  • votex_link_fill_card

    Live

    params: 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 soon

    params: 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 soon

    params: None

    Legacy metadata-only tool. Virtual cards are coming soon; issuing is disabled.

  • votex_freeze_virtual_card

    Not offeredComing soon

    params: 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_paid works without PCI or an issuer. Vault purchases, fill_card and 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_screenshot is available, but screenshots are disabled after fill_card for 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 }