# Personal Wallet Payment System AI Merchant API

Base URL: `https://web8889.com`

## Current capabilities

- Hosted checkout for supported assets.
- Fixed-price payment links.
- Dynamic per-order checkout links created by an authenticated merchant backend.
- Authenticated payment-status polling for fulfillment after payment verification.
- Payment records with order IDs and transaction hashes.
- AI product creation API for active Basic, Agent Pro, and Platinum merchants.
- Agent Pro receipt-printer automation endpoints.
- Receipt printer job polling and acknowledgement.

## Authentication

Merchant API endpoints use a server-side merchant API key:

```http
Authorization: Bearer mm_api_...
```

Create or rotate the key in the dashboard's **AI Merchant API** panel. The full key is shown once. Keep it on your server; never put it in browser JavaScript, a public repository, or a buyer-facing page. Revoke it if exposed. Dynamic Checkout and API-key management are available to active Basic, Agent Pro, and Platinum subscriptions. API access stops when the subscription expires.

## Discovery

- `GET /api/public/agent-capabilities` — credential-free current capability document.
- `GET /openapi.json` — machine-readable API description.
- `GET /.well-known/agent.json` — agent discovery manifest.

## Available merchant endpoints

| Method | Endpoint | Access |
|---|---|---|
| GET | `/api/merchant/code-products` | Active subscription + dashboard session or merchant API key |
| POST | `/api/merchant/code-products` | Active subscription + dashboard session or merchant API key; creates or updates one fixed-price product |
| POST | `/api/merchant/code-products/bulk` | Active subscription + dashboard session or merchant API key; imports multiple fixed-price products |
| POST | `/api/merchant/checkout-sessions` | Active Basic, Agent Pro, or Platinum subscription + dashboard session or merchant API key; creates one order-specific checkout |
| GET | `/api/merchant/checkout-sessions/{paymentSessionId}` | Same authentication; returns the merchant-owned order's verified status |
| GET | `/api/merchant/printer/jobs?status=pending` | Active Agent Pro subscription + API key |
| POST | `/api/merchant/printer/jobs/{jobId}/printed` | Active Agent Pro subscription + API key |

## Create an AI product link

The AI or website backend sends the chosen price to the merchant API. The server derives the plan from the authenticated merchant account, saves the price, and returns the generated product code and signed website snippet. The buyer's browser cannot change the saved price.

```http
POST /api/merchant/code-products
Authorization: Bearer mm_api_...
Content-Type: application/json

{
  "siteName": "Hat Shop",
  "productTitle": "Canvas Hat",
  "productCode": "canvas-hat-10",
  "unitPrice": "10.00",
  "tokenSymbol": "USDC",
  "productType": "product",
  "billingTermDays": 0
}
```

Use a stable `productCode` when retrying or updating the same active item; omitting it creates a new product slot. Basic, Agent Pro, and Platinum links use separate lists and quotas: Basic 20, Agent Pro 100, and Platinum 1,050. A new link at the cap invalidates the oldest active link in that tier only. An invalidated product code cannot be reactivated; create a new code. A product's price is fixed in the backend after it is saved, and updates to an active product keep its code. Fixed product settlement is USDC. Buyer payment assets are offered only when the wallet balance and a live route quote qualify.

## Create a dynamic game, app, or website order

Use this when each sale may have a different amount (for example, game currency, skins, or materials). Call the API from your trusted backend after your own game/site has decided the price. The API returns a hosted checkout link for that single order; the buyer cannot change the amount. Integrate this once in your server so customers do not log in to this Dashboard for each purchase.

```http
POST /api/merchant/checkout-sessions
Authorization: Bearer mm_api_...
Content-Type: application/json

{
  "merchantOrderId": "game-order-1042",
  "productTitle": "Blue skin",
  "description": "Limited-edition skin",
  "amount": "10.00"
}
```

The response includes `paymentSessionId`, `checkoutUrl`, `amount`, `status`, and `expiresAt`. Send `checkoutUrl` to the buyer. Your server polls `GET /api/merchant/checkout-sessions/{paymentSessionId}` and fulfills the order only when the verified status is `paid`. Do not trust a browser redirect or a transaction hash supplied by the buyer as proof of payment.

`merchantOrderId` is required, unique per merchant, and may contain letters, numbers, dots, underscores, colons, and hyphens. Reusing one returns `409` and does not create a second payment session. Amount must be a decimal string from `1.00` through `10000000.00` USDC with at most two decimal places. Sessions expire after 15 minutes by default; `expiresInMinutes` can be set from 5 to 60. Create a new session if an unpaid checkout expires.

```bash
curl -X POST https://web8889.com/api/merchant/checkout-sessions \
  -H 'Authorization: Bearer mm_api_...' \
  -H 'Content-Type: application/json' \
  -d '{"merchantOrderId":"game-order-1042","productTitle":"Blue skin","amount":"10.00"}'

curl https://web8889.com/api/merchant/checkout-sessions/SESSION_ID \
  -H 'Authorization: Bearer mm_api_...'
```

## Payment model

EVM routes settle as Base USDC after checkout verification. Solana assets are shown only when a configured Solana receiving path exists. A successful payment is associated with an order ID and transaction hash. The buyer still signs the transaction in their own wallet.

## Not available yet

The following are planned and must not be assumed to be live:

- Direct autonomous agent checkout / AgentPay Intent creation.
- MCP/UCP integration.

See [OpenAPI](./openapi.json) for request and response schemas.