request_payment
Request payment approval
Request the user's approval to pay for a purchase.
Usually returns `{auto_approved: false, approval_url}` — show the approval_url to the user
so they can review the total and approve with one tap, then call get_payment_result.
If the user's spending policy auto-approves this purchase (e.g. under their cap at an
allowlisted merchant), it returns `{auto_approved: true, status: "approved", card}` immediately
— no approval needed, just use the card.
Args:
amount: Total to charge, in major units (e.g. 18.50 dollars).
merchant: Human-readable merchant / store name shown on the approval screen.
line_items: Optional list of {"name": str, "quantity": int, "amount_cents": int}.
currency: ISO currency code, default "usd".
輸入參數amount必填currencymerchant必填line_items
get_payment_result
Get payment result
Poll for the outcome of a payment request.
Long-polls up to wait_seconds. Returns status one of: pending, approved, settled,
declined, expired, not_found, claim_pending. When approved, includes a single-use
`card` (number, cvc, exp) locked to this purchase — use it to complete checkout at
the merchant. If still "pending"/"claim_pending", call again.
For a claim (charge_id = the "clm_…" poll_id from request_payment): pass the
agent_secret you received. The first approved result also contains `connect_token` —
persist it and send it as the Authorization bearer on all future calls.
輸入參數charge_id必填agent_secretwait_seconds
list_payment_requests
List payment requests
List this agent's payment requests and whether each has been approved yet.
Use this to see the state of every request you've made — not just poll one saved
charge_id. Each item includes its `status` (pending, approved, settled, declined,
expired) so you can tell which are still waiting and which the user has acted on.
For a pending request it also returns the `approval_url` (re-surface it to the user);
once a request is approved, call get_payment_result(charge_id) to fetch the card.
Args:
status: which to return — "open" (default, still-pending only) or "all".
limit: max requests to return (default 20, capped at 100), newest first.
輸入參數limitstatus
record_order
Record merchant order reference
Report the merchant's order reference back after checkout, so the user can later reverse
(refund) the purchase. `order_ref` is the merchant's payment id (e.g. a Stripe PaymentIntent).
輸入參數charge_id必填order_ref必填
request_subscription
Request subscription approval
Set up a recurring subscription mandate (e.g. Netflix at up to $16/month).
Requires the user's explicit one-time approval — returns an approval_url. The mandate is
merchant-locked and capped: the merchant can never charge more than `cap` per period, and the
user can cancel anytime (after which the merchant can never charge again).
Args:
merchant: merchant to authorize (e.g. "Netflix").
cap: max amount per period in major units (e.g. 16.00).
interval: "weekly" | "monthly" | "yearly".
輸入參數cap必填intervalmerchant必填
list_subscriptions
List subscriptions
List the user's subscription mandates and their status.
無需輸入參數。
cancel_subscription
Cancel subscription
Cancel a subscription mandate. Safe — canceling never spends money, and the merchant can
never charge again afterwards.
輸入參數mandate_id必填
