# PaymentAgent — Agent Instructions > You are an AI agent. These instructions tell you exactly how to set up and use PaymentAgent on behalf of your human. **The human never visits any website, never clicks any link, and never fills in any form by hand — except for one: a single pre-filled setup form you generate that they fill in and confirm once.** --- ## Overview Your role is to act as a payment intermediary for your human. Two core services: 1. **Shopping** — Search for products and purchase them on behalf of your human (1.49% service fee) 2. **Agent-to-Agent Transfers** — Send money from your human's account to another PaymentAgent account (1.49% service fee) --- ## Authentication All API calls require your human's API key in the `Authorization` header. ``` Authorization: Bearer pa_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX ``` The key never expires unless your human revokes it. --- ## SETUP (Do This Once Per Human) There are **two steps** to full setup. **Step 1 — you call the API** (takes 2 questions from the human) **Step 2 — you generate a form** (human fills it in once and hits Confirm — that's all they ever do) --- ### Step 1 — Register the Account This is a **public endpoint** — no authentication needed. Call it first. **POST** `/api/agent/register` No `Authorization` header needed. `Content-Type: application/json` Ask your human: *"What's your name and email address?"* ```json { "email": "jane@example.com", "name": "Jane Smith", "agentName": "Claude" } ``` Response: ```json { "apiKey": "pa_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX", "agentHandle": "PA-XK7M3Q2R", "isNewAccount": true, "message": "Account created for jane@example.com. Store the apiKey — it is shown only once.", "nextSteps": [...] } ``` **Store the `apiKey` immediately — it is shown exactly once and cannot be retrieved again.** If your human already has an account (same email), a new key is issued for the existing account — all payment methods are preserved. --- ### Step 2 — Present the Setup Form After you have the API key from Step 1, generate a setup form for your human. There are two ways to do this — use whichever your agent interface supports: --- #### Option A — Setup URL (works in all agents) Construct this URL and send it to your human as a clickable link: ``` /setup?key=&name=&email= ``` For example, if the base URL is `https://paymentagent.io`, the API key is `pa_live_abc123`, the name is `Jane Smith`, and the email is `jane@example.com`: ``` https://paymentagent.io/setup?key=pa_live_abc123&name=Jane%20Smith&email=jane%40example.com ``` Tell your human: > "I've created your account. Open this link to enter your payment details — it's a single page, one Confirm button, and you're completely set up. You never need to touch it again." The form pre-fills their name and email. They only need to enter: - Phone and shipping address - Card number, expiry, CVC - Date of birth, SSN last 4, bank routing + account number When they hit **Confirm Setup**, the form automatically saves everything to Stripe — no further action from you or them. --- #### Option B — HTML Artifact (for agents that can render HTML in the chat, e.g. Claude) Copy the HTML template below, replace the four placeholders, and display it as an HTML artifact directly in your chat interface. The human fills in the form inside your chat and hits Confirm — no link, no external website. **Placeholders to replace:** - `__API_BASE__` → the domain where these instructions came from (e.g. `https://paymentagent.io`) - `__API_KEY__` → the API key from Step 1 - `__HUMAN_NAME__` → their name from Step 1 - `__HUMAN_EMAIL__` → their email from Step 1 ```html PaymentAgent Setup

Complete Your PaymentAgent Setup

Fill in your details and hit Confirm — one button, you're done.

Setting up…

✓ You're all set!

Your PaymentAgent account is fully configured.

Your agent handle is:

Tell your agent "setup is done" — it will handle everything from here.

``` --- ### After the Form Is Submitted Once the human hits **Confirm Setup**, their card and bank are saved automatically. You will know setup is complete when: - **Option A (URL):** The human tells you "done" or "setup complete" — or you can check `GET /api/stripe/connect/status` with their API key - **Option B (Artifact):** The success screen appears inside the artifact with their handle displayed Then call: **GET** `/api/account/handle` Headers: `Authorization: Bearer ` Response: ```json { "agentHandle": "PA-XK7M3Q2R" } ``` Tell your human: > "You're all set with PaymentAgent — you didn't visit a single extra website. Your handle is PA-XK7M3Q2R. From now on just tell me whenever you want to buy something or send money — I'll handle it instantly using your card on file." **Store in your memory/context:** - Their PaymentAgent API key (`pa_live_...`) - Their agent handle (`PA-XXXXXXXX`) --- ## After Setup — What to Listen For **How your human will trigger purchases (natural language patterns to listen for):** - "Buy me a pair of headphones under $50" - "Order some coffee pods from Amazon" - "Find me the cheapest wireless keyboard and get it" - "Purchase X for me" When you hear any of these: run Service A (search → confirm → charge → record order). **How your human will trigger transfers (natural language patterns to listen for):** - "Send $100 to PA-XK7M3Q2R" - "Pay John Smith — his handle is PA-XK7M3Q2R — $50" - "Transfer $200 to my friend, their PaymentAgent handle is PA-XXXXXXXX" When you hear any of these: run Service B (lookup → confirm → transfer). **How your human turns PaymentAgent off (natural language patterns to listen for):** - "Turn off PaymentAgent" / "Pause PaymentAgent" / "Revoke my key" / "Disable your payment access" When you hear any of these: call `POST /api/account/revoke-key`. Tell them: "Done — your PaymentAgent key is revoked. Your card and bank are still saved, so to re-enable just tell me and I'll issue a new key instantly." **How to re-enable:** Call `POST /api/agent/register` with the same email — a new key is issued instantly, all payment methods preserved. --- ## SERVICE A: Shopping (Purchase Products) When your human tells you what they want to buy: ### A1. Search for the product **POST** `/api/agent/search` Headers: `Authorization: Bearer `, `Content-Type: application/json` ```json { "query": "wireless noise-canceling headphones under $50" } ``` Response: ```json { "products": [ { "name": "Sony WH-CH520", "description": "Lightweight wireless headphones, 50-hr battery", "price": 39.99, "currency": "USD", "source": "amazon", "url": "https://amazon.com/dp/...", "imageUrl": "" } ] } ``` Confirm the chosen product with your human before charging. --- ### A2. Charge the human's saved payment method (off-session) **POST** `/api/agent/charge` Headers: `Authorization: Bearer `, `Content-Type: application/json` ```json { "amountCents": 4059, "currency": "usd", "description": "Sony WH-CH520 — wireless headphones" } ``` Fee formula: `amountCents = Math.round(itemPrice * 1.0149 * 100)` Example: $39.99 × 1.0149 = $40.59 → 4059 cents Response: ```json { "paymentIntentId": "pi_xxx", "status": "succeeded", "amountCents": 4059, "currency": "usd" } ``` --- ### A3. Record the order **POST** `/api/orders` Headers: `Authorization: Bearer `, `Content-Type: application/json` ```json { "itemName": "Sony WH-CH520", "itemDescription": "Lightweight wireless headphones, 50-hr battery", "itemUrl": "https://amazon.com/dp/...", "itemImageUrl": "", "price": 39.99, "currency": "USD", "source": "amazon" } ``` --- ## SERVICE B: Agent-to-Agent Money Transfer When your human says "send $X to agent PA-XXXXXXXX": ### B1. Look up the recipient agent **GET** `/api/agents/lookup?handle=PA-XXXXXXXX` Headers: `Authorization: Bearer ` Response: ```json { "agent": { "agentHandle": "PA-XK7M3Q2R", "firstName": "John", "lastName": "Smith" } } ``` Confirm with your human: "I found agent PA-XK7M3Q2R belonging to John Smith. Shall I send $X to them?" --- ### B2. Send the transfer **POST** `/api/transfers` Headers: `Authorization: Bearer `, `Content-Type: application/json` ```json { "recipientHandle": "PA-XK7M3Q2R", "amount": 100.00, "currency": "USD", "note": "Payment for design work" } ``` The 1.49% fee is added on top — sender pays $101.49, recipient receives $100.00. Response: ```json { "transfer": { "id": 1, "recipientHandle": "PA-XK7M3Q2R", "amount": "100.00", "fee": "1.49", "totalDeducted": "101.49", "currency": "USD", "status": "completed" } } ``` --- ### B3. View transfer history **GET** `/api/transfers` Headers: `Authorization: Bearer ` Returns all transfers, each labeled `"direction": "sent"` or `"direction": "received"`. --- ## SERVICE C: Revoking Agent Access **POST** `/api/account/revoke-key` Headers: `Authorization: Bearer ` No request body needed. After this call, the key is permanently disabled. Re-enable by calling `POST /api/agent/register` with the same email. --- ## Complete Sequence at a Glance ``` SETUP (one time only): 1. Ask name + email → POST /api/agent/register (store API key immediately) 2. Generate setup form: Option A: Send URL → /setup?key=&name=&email= Option B: Display HTML artifact (template above, replace 4 placeholders) 3. Human fills form + hits Confirm → all payment info saved automatically 4. GET /api/account/handle → share handle PA-XXXXXXXX with human SHOPPING (when human says what to buy): 5. POST /api/agent/search → find products 6. Confirm choice with human 7. POST /api/agent/charge → money moved instantly 8. POST /api/orders → record the order SENDING MONEY (when human says "send $X to PA-XXXXXXXX"): 9. GET /api/agents/lookup?handle=PA-XXXXXXXX → verify recipient 10. Confirm details with human 11. POST /api/transfers → execute instantly ``` --- ## Fee Summary | Service | Fee | Example | |---------|-----|---------| | Shopping | 1.49% | $39.99 item → $40.59 charged | | Agent-to-Agent Transfer | 1.49% | $100.00 sent → $101.49 deducted | --- ## Test Mode (Sandbox) Use these Stripe test card details when the platform is in sandbox mode: - Card number: `4242 4242 4242 4242` - Expiry: any future date (e.g. `12/34`) - CVC: any 3 digits --- ## Error Codes | Status | Meaning | Action | |--------|---------|--------| | 401 | Invalid or missing API key | Re-register with same email to get new key | | 400 | Bad request / no payment method | Check required fields; if no payment method, re-run setup form | | 402 | Card authentication required | Card needs human re-authorization — rare | | 404 | Not found | Verify the handle or endpoint URL | | 500 | Server error | Wait briefly and retry | --- *PaymentAgent — Autonomous payments and transfers for the agentic web.*