Quartermaster eSIM MCP Server

Sandbox only. Marks the order's eSIM as installed and used, as if the traveler activated it. Use it to exercise refund and dispute rules.

Sandbox only. Acts as the principal paying a get_topup_link URL: the mock provider sends a PayPlus-format IPN through the same webhook path production uses, and the wallet is credited. outcome "declined" simulates a failed card.

Every agent registered for your principal: agent_id, created_at, principal_key_version, status (active, expired or revoked), mandate_expiry and limits, plus active_agents against max_agents_per_principal. Needs your agent credentials and the principal_key (argument or X-Principal-Key header). An agent you do not recognise may have been registered with a leaked principal_key: revoke it, or rotate the key.

Current order state, eSIM delivery payload, activation and data usage from the supplier, receipts, and the latest disputes (disputes_total counts all). Any agent of the order's principal may call it (and regenerate_activation and request_refund) for the order; other principals get ORDER_NOT_FOUND.

Search eSIM data plans from trusted suppliers. Filter by destination country (ISO 3166-1 alpha-2) or region, minimum data, validity and price. Results are sorted by final price unless sort says otherwise. Suppliers below the trust threshold are excluded and listed in excluded_suppliers.

Returns every policy as machine-readable JSON (mandate, refund, dispute, supplier trust, registration), the store terms and the product/agent JSON Schemas, so you can reason about terms before buying.

Buy the product in a quote. Enforces the mandate and the wallet policy, holds the amount in the principal's wallet, orders from the supplier, debits the wallet, and returns the order with the eSIM delivery payload and a signed receipt. If the wallet is short, fails with WALLET_INSUFFICIENT_FUNDS and a ready top-up link for the principal. idempotency_key is required: reusing it returns the original order and never charges twice; while the original call is still running it answers ORDER_IN_PROGRESS (retryable, retry_after_seconds, order_id: repeat the same call later or poll order_status). QUOTE_PRICE_CHANGED (retryable): the plan's price went up since the quote (error.details.quoted_price and current_price); nothing was held or charged, get a new quote. If the supplier's answer is unknown (timeout, network error), the order stays "processing" with supplier_outcome "unknown" and the price held, not debited: poll order_status and do not buy again with a new key. Only SUPPLIER_FAILURE with retryable=true calls for a new quote and key. PRINCIPAL_FROZEN (not retryable): a top-up was reversed after its credit was spent, or the operator froze the principal; get_topup_link still works and the next credit settles the debt first.

Lock the final price for one product for a short time (quote_ttl_seconds in store terms). Also returns a mandate pre-check and the refund terms, so you know before buying whether the purchase will be allowed.

For a delivered order of your principal (bought by any of its agents) whose activation code (QR / LPA) does not install: asks the supplier for a fresh code and returns the new delivery payload. The previous code may stop working. Not every supplier supports it (NOT_SUPPORTED_BY_SUPPLIER); then open a dispute with reason not_working.

Create an agent identity bound to a principal, with a spending mandate (limits in minor units). Returns agent_key once; send it on every later call. The first agent of a new principal_id also receives principal_key (once): the principal owns the wallet, and every later register_agent for that principal_id must present principal_key (argument or X-Principal-Key header), else PRINCIPAL_KEY_REQUIRED. New agents are capped by the registration policy (see get_policies); only active agents (not revoked, mandate unexpired) count toward max_agents_per_principal. To extend or change an existing agent's mandate, use renew_mandate. Agents brought by a partner of the store also send partner_id and partner_key (both or neither): a new principal is attributed to that partner for good. Invalid partner credentials give PARTNER_INVALID; an existing principal keeps the attribution it was created with (PARTNER_MISMATCH for another partner, PARTNER_ATTRIBUTION_LOCKED if it has none). Attribution changes nothing about prices or limits.

Re-sign the mandate of an existing agent of your principal (you, unless target_agent_id names another) with new limits and expiry, under the same registration policy caps as register_agent. Needs your agent credentials and the principal_key (argument or X-Principal-Key header). The agent keeps its agent_id, agent_key and spend history. Use it on MANDATE_EXPIRED or to change limits instead of registering a new agent; an agent whose mandate had expired takes a slot again (PRINCIPAL_AGENT_LIMIT when none is free). Revoked agents cannot be renewed (AGENT_REVOKED).

Reasons "unused" and "changed_plans" are voluntary refunds under the refund policy. Reasons "not_delivered", "not_working" and "duplicate_purchase" open a dispute under the dispute policy, which can refund fully, partially, reject, or escalate to a human. A dispute about a delivered eSIM is credited automatically only when the supplier confirms it cancelled the eSIM; otherwise, and for partial refunds, it is escalated (outcome "escalate", reason DISPUTE_SUPPLIER_CANCEL_UNCONFIRMED). Orders the supplier has not confirmed yet are refused with ORDER_AWAITING_SUPPLIER (poll order_status). An order takes one escalated dispute at a time (DISPUTE_ALREADY_OPEN until a human decides it) and a limited number of disputes in all (DISPUTE_LIMIT_REACHED). Any agent of the principal that owns the order may ask. ORDER_CHANGED is retryable. After a full refund, order_status no longer returns the activation code. Denials return error.code = the policy reason_code.

Revoke an agent of your principal for good: it can no longer authenticate (AGENT_REVOKED) and no longer holds a slot under max_agents_per_principal. Needs your agent credentials and the principal_key (argument or X-Principal-Key header). Its orders stay visible to the principal's other agents. Repeating it changes nothing (already_revoked).

Replace your principal's principal_key. Needs your agent credentials and the current principal_key (argument or X-Principal-Key header). Returns the new key once; the old one stops working. Every agent registered under the previous key is revoked for good (AGENT_REVOKED) except you and the agents in keep_agent_ids (list_agents shows them); the result lists kept_agent_ids and revoked_agent_ids. A principal registered before keys existed has none: any of its agents can call this without principal_key to mint the first one, which revokes nobody.

Create a hosted payment URL to hand to your human principal. They pay in ILS on the acquirer's page (PayPlus); you never see card data. amount_minor is in `currency`: USD (the wallet credit you want; the ILS charge is computed at today's rate) or ILS (the exact charge). The wallet is credited in USD at the rate in force when payment is confirmed. Limits are in the topup policy.

Ordered steps to relay to the traveler when an order's eSIM does not install (cant_install_qr) or does not work (no_data, no_signal, slow), worded for the phone (device.os ios or android, device.model if known): eSIM compatibility and carrier lock, install by QR or manual entry (SM-DP+ address and activation code), data roaming on the eSIM line, the eSIM as the data line, the APN when the plan has one, airplane-mode toggle and restart, then the escalation (regenerate_activation, request_refund with reason not_working and the evidence to include, or order_status for a code not delivered yet). Also returns the order's status and the plan's APN, networks and network types (plan_facts); activation and usage only as the supplier reports them. Read-only: it reissues nothing and opens no dispute. Any agent of the order's principal may call it; other principals get ORDER_NOT_FOUND. A refunded or failed order gets no steps.

Check a receipt's signature and that it matches its hash-chained ledger entry.

Balance, available funds (balance minus pending holds), open (unpaid) top-up links, top-ups awaiting confirmation, recent top-ups and recent ledger entries of the wallet of the principal you act for. Shared by all of the principal's agents. Amounts in minor units. topups_awaiting_confirmation: a payment was reported for these and is being confirmed with the payment provider; never send their links again, the balance updates once it is confirmed. frozen and debt: a top-up reversed by the payment provider (refund, cancellation, chargeback) is taken back from the balance; what the balance could not cover is a debt that blocks purchases until a top-up settles it. principal.partner_id: the partner the principal was attributed to at registration, if any.