# Locus Checkout

> **You are on:** `https://paywithlocus.com/` · `https://api.paywithlocus.com/api` | [llms.txt](https://paywithlocus.com/llms.txt)
>
> Locus has three environments. Keep every landing, API, approval, and skill URL in the environment that issued the `claw_` key:
> - **Production**: paywithlocus.com / {api}.paywithlocus.com
> - **Beta**: {beta}.paywithlocus.com / {beta-api}.paywithlocus.com
> - **Stage**: {stage}.paywithlocus.com / {stage-api}.paywithlocus.com

Use this skill when a user asks you to find, compare, or buy a product. It combines product discovery, browser navigation, the user's cardholder-approved Visa, and merchant checkout. It also covers a Locus Checkout session when the user gives you a session ID or Locus checkout link.

**Base URL:** `https://api.paywithlocus.com/api`
**Auth:** `Authorization: Bearer $LOCUS_API_KEY`

## Choose the Payment Path

| User intent | Path |
|---|---|
| “Find and buy headphones,” “order this item,” or any ordinary web-store purchase | [Open-web purchase](#open-web-purchase) |
| A Locus checkout URL or session ID | [Locus Checkout session](#locus-checkout-session) |
| Send USDC to an address or email | [SKILL.md](SKILL.md) |
| Buy a new prepaid virtual card | [LASO.md](LASO.md) |

Do not confuse a Locus Checkout session with an open-web card purchase. The former pays USDC to a Locus merchant session; the latter charges the user's enrolled Visa and produces single-use checkout credentials.

## Open-Web Purchase

### 1. Clarify the request

Ask only for details that change the result. Common missing details are:

- item or outcome;
- maximum all-in budget;
- quantity, size, color, model, condition, or compatibility;
- delivery deadline and shipping country/postal code;
- merchant restrictions, membership requirements, or acceptable substitutes.

If the user gave a specific product URL and said to buy it, do not restart broad research. Verify the item, availability, and final total, then continue.

Before any charge, present a compact purchase summary with the exact item, seller, condition/variant, quantity, shipping method, return caveats, and all-in total. Ask for confirmation unless the user already approved that exact purchase and total in the current conversation. Never silently substitute a different seller, variant, condition, subscription, warranty, or recurring plan.

### 2. Find and compare products

Prefer a structured product endpoint when one exists, then use browser navigation for cart and checkout. Parse-backed marketplace endpoints cover stores such as Walmart, IKEA, eBay, Home Depot, Target, Amazon, Nike, Newegg, and others.

1. Search `https://paywithlocus.com/wapi/index.md` for the merchant.
2. Fetch `https://paywithlocus.com/wapi/<provider>.md` and follow its current schema.
3. Call the documented `search_products`, `get_product_details`, availability, offers, or reviews endpoints through:

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/<provider>/<endpoint> \
  -H "Authorization: Bearer $LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: product-research-UNIQUE_ID" \
  -d '{"query":"wireless headphones","page":1}'
```

Parse is a research accelerator, not an authority for the final charge. Re-check the merchant page for live price, seller, stock, shipping, tax, and variant before asking the cardholder to approve.

If no useful structured endpoint exists, use web search or a browser. Do not block the purchase merely because Parse has no matching provider.

### 3. Prepare checkout before charging

Use an interactive browser or Browser Use to reach the final review screen without placing the order. Collect the exact all-in total, including tax, shipping, tips, deposits, and mandatory fees.

For a non-sensitive Browser Use task:

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/browser-use/run-task \
  -H "Authorization: Bearer $LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: checkout-preview-UNIQUE_ID" \
  -d '{
    "task":"Open the product, select the requested variant and quantity, proceed to the final review screen, report the itemized total, and STOP before entering payment or placing the order.",
    "startUrl":"https://merchant.example/product",
    "maxSteps":40
  }'
```

Poll the returned task ID with `browser-use/get-task-status`, then read the result with `browser-use/get-task`. Browser tasks may be stateless; do not assume a cart or login survives into a later task.

### 4. Check the card

```bash
curl https://api.paywithlocus.com/api/pay/cards \
  -H "Authorization: Bearer $LOCUS_API_KEY"
```

Use only a card with `ready_for_charges: true`. If there is one, identify it as `Visa 4242` (or the returned brand and last four) and continue. If there are several, ask which card to use unless the user already named one. Never expose or request the underlying physical card number.

If no card is ready, send the user to `https://app.paywithlocus.com/cards`. They must finish consent, issuer verification, and Visa Payment Passkey enrollment in the browser before the agent can charge it.

### 5. Initiate the exact charge

Read [CARDS.md](CARDS.md) for the full request schema and error catalog. Use the exact merchant and all-in total from the final review screen:

```bash
curl -X POST https://api.paywithlocus.com/api/pay/charge-card \
  -H "Authorization: Bearer $LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "card_id":"CARD_ID",
    "amount":29.99,
    "currency":"USD",
    "description":"Blue wireless headphones, quantity 1",
    "merchant":{"name":"Merchant","url":"https://merchant.example","country_code":"US"},
    "idempotency_key":"merchant-item-variant-logical-attempt"
  }'
```

Send the returned `approval_url` to the user and state the item, merchant, amount, and card last four beside it. Every real-card charge requires the user's Visa passkey approval.

Poll no faster than every 10 seconds:

```bash
curl https://api.paywithlocus.com/api/pay/charge-status/CHARGE_ID \
  -H "Authorization: Bearer $LOCUS_API_KEY"
```

Continue only when status is `completed` and `credentials` are present. Stop on `denied`, `expired`, or `failed`.

### 6. Complete the merchant checkout

Use the single-use credentials before `credentials_expires_at`. Never print them to the user, put them in chat, save them to disk, add them to shell history, or include them in a browser task's natural-language `task` field.

Preferred order:

1. Use a local interactive browser tool and type the credentials directly into the merchant's secure payment form.
2. If using Locus Browser Use, pass payment and shipping values only through its domain-scoped `secrets` field. Restrict `allowedDomains` to the merchant, disable vision, and disable recording. Locus redacts the secret values from its durable request records.

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/browser-use/run-task \
  -H "Authorization: Bearer $LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: secure-checkout-UNIQUE_ID" \
  -d '{
    "task":"Buy the previously approved item. Use the domain-scoped checkout secret for payment and delivery. Verify the final total is exactly $29.99; if it differs, STOP without placing the order. Do not add warranties, memberships, tips, substitutions, or recurring plans. Return the confirmation number and final total.",
    "startUrl":"https://merchant.example/product",
    "maxSteps":60,
    "secrets":{"merchant.example":"card_number=...; expiration_month=...; expiration_year=...; cvc=...; cardholder_name=...; shipping_name=...; shipping_address=...; email=..."},
    "allowedDomains":["merchant.example"],
    "vision":false,
    "sessionSettings":{"enableRecording":false}
  }'
```

Replace the example values in memory when constructing the request. Do not write a JSON file containing them. If the secure task would cross the agent's wrapped-API approval threshold, Locus rejects delayed storage; lower `maxSteps` or use an interactive browser.

At the final review screen, compare the total against the approved card charge:

- Exact match: place the order once.
- Any increase or material merchant/item change: stop. Do not submit the one-time card. Explain the change, then create a new charge only after the user confirms.
- Merchant decline or ambiguous submit result: do not immediately mint another charge or click again. Check for a confirmation page/email and report the ambiguity.

After success, return the merchant, items, final total, order/confirmation number, delivery estimate, and receipt location. Do not include card credentials.

## Locus Checkout Session

Use this branch only for a Locus-hosted merchant checkout session.

```bash
# 1. Preflight
curl https://api.paywithlocus.com/api/checkout/agent/preflight/SESSION_ID \
  -H "Authorization: Bearer $LOCUS_API_KEY"

# 2. Pay
curl -X POST https://api.paywithlocus.com/api/checkout/agent/pay/SESSION_ID \
  -H "Authorization: Bearer $LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"payerEmail":"buyer@example.com"}'

# 3. Poll
curl https://api.paywithlocus.com/api/checkout/agent/payments/TRANSACTION_ID \
  -H "Authorization: Bearer $LOCUS_API_KEY"
```

Statuses progress from `PENDING` to `QUEUED` to `PROCESSING`, then `CONFIRMED`, `FAILED`, or `POLICY_REJECTED`. Poll every two seconds. A merchant should fulfill only after authoritative confirmation.

## Recovery Rules

| Problem | Action |
|---|---|
| No ready card | Ask the user to finish setup at `/cards`, then list cards again |
| User did not receive approval email | Share `approval_url` directly or point them to `/approvals` |
| Approval expired or was denied | Stop and ask before creating a new logical charge |
| Final checkout total changed | Stop before payment; reconfirm and create a correctly sized charge |
| Browser task failed before submit | Re-run with the same logical Browser Use idempotency key only when Locus reports the call as retryable |
| Submit result is ambiguous | Look for an order confirmation; never double-click or issue a second charge blindly |
| Card declined after submit | Treat the single-use credential as consumed until proven otherwise; report the failure |
| Merchant requires unsupported human verification | Pause and ask the user to take over that step |

## Non-Negotiable Safety Rules

- The user chooses the product and approves the exact purchase; the agent executes it.
- One logical purchase gets one card-charge idempotency key and one merchant submission.
- Card credentials are short-lived, amount-locked, merchant-bound, and single-use.
- Never place payment secrets in prompts, logs, files, screenshots, recordings, or ordinary request audit data.
- Never buy restricted goods or work around merchant, cardholder, Visa, or Locus controls.