# QRBayad agent setup

These are instructions for an AI agent. Do the steps yourself where you can. Ask the user only for things you cannot get on your own (their API key, and approval before changing their code).

QRBayad accepts QR Ph payments (GCash, Maya, any PH bank app) straight into the merchant's bank account and confirms them automatically. Full API reference: https://qrbayad.com/docs.md

## 1. Get an API key
Ask the user to open https://qrbayad.com/dashboard/developers, click **Create secret key** (or **Roll key**), and give it to you. If they have no account yet, send them to https://qrbayad.com/signup first. Setup takes about 5 minutes and ends with a ₱1 test payment.

Store it as an environment variable, never in code:

```
QRBAYAD_API_KEY=sk_live_...
```

## 2. Pick what the user wants

### A) Connect the QRBayad MCP server (to create links and check payments from chat)

Claude Code:
```bash
claude mcp add --transport http qrbayad https://qrbayad.com/mcp --header "Authorization: Bearer $QRBAYAD_API_KEY"
```

Codex:
```bash
codex mcp add qrbayad --url https://qrbayad.com/mcp --bearer-token-env-var QRBAYAD_API_KEY
```

Cursor (`.cursor/mcp.json`), VS Code / GitHub Copilot (`.vscode/mcp.json`, key `servers`), Windsurf and others that accept a remote URL:
```json
{
  "mcpServers": {
    "qrbayad": {
      "url": "https://qrbayad.com/mcp",
      "headers": { "Authorization": "Bearer sk_live_..." }
    }
  }
}
```

Then reload the agent. Tools: create_payment_link, get_payment_link, list_payment_links, list_payments, get_account.

### B) Integrate QRBayad payments into the user's app
1. Server-side, create a checkout when the customer checks out:
   `POST https://qrbayad.com/api/v1/checkouts` with `{"amount": <centavos>, "description": "...", "reference_id": "<order id>"}`
2. Redirect the customer to the returned `checkout_url` (or render `qr_payload` as a QR code).
3. Add a webhook route that verifies `QRBayad-Signature` (see https://qrbayad.com/docs.md#webhooks) and marks the order paid on `checkout.paid`, using `data.checkout.reference_id` to find it.
4. Ask the user to paste the webhook URL into https://qrbayad.com/dashboard/developers and store the signing secret as `QRBAYAD_WEBHOOK_SECRET`.
5. Test: create a ₱1 checkout and ask the user to pay it from GCash. The page should flip to paid and the webhook should fire within seconds.

## Rules
- Amounts in the REST API are centavos. MCP `create_payment_link` takes pesos.
- Never expose `sk_live_` keys in client-side code or commit them.
- QRBayad never holds funds and cannot refund. Refunds are sent manually by the merchant from their bank app.

When done, tell the user what you connected or changed and how to test it.