# UWS Payments — Complete AI & Developer Reference (llms-full.txt)

## 1. Executive Overview (EN / KO)
- **English**: UWS Payments (https://uwspayments.com) is a Unified Multi-Project PG Router & Payment Gateway API. By registering Toss Payments (Single, Billing, PayPal) and Stripe keys once, developers can issue domain-bound API keys for multiple services and trigger checkouts, confirm payments, process refunds, and receive webhooks via a single unified API.
- **한국어**: UWS Payments (https://uwspayments.com)는 등록된 토스페이먼츠(단건·빌링·페이팔) 및 Stripe 키를 기반으로 여러 외부 프로젝트와 도메인에서 단일 API 호출만으로 결제를 요청·승인·취소할 수 있는 통합 PG 라우터 게이트웨이입니다. 키 발급 시 입력한 서비스명과 도메인이 모든 결제 로그에 자동 기록됩니다.

## 2. Supported PG Routes & Currencies
| PG Parameter (`pg`) | Payment Method | Default Currency | Description |
| :--- | :--- | :--- | :--- |
| `toss` | Toss Payments Single Checkout | KRW | Domestic Korean credit/debit cards & easy pay |
| `toss_billing` | Toss Payments Billing Key | KRW | Recurring subscription card registration & auto-charge |
| `toss_paypal` | Toss Payments Global PayPal | USD | International PayPal checkout via Toss v2 Standard SDK |
| `stripe` | Stripe Checkout | USD | Global credit cards via Stripe Checkout Sessions |

## 3. cURL Example (Create Hosted Payment Session)
```bash
curl -X POST "https://uwspayments.com/api/v1/payments/request" \
  -H "X-API-KEY: YOUR_UWS_PAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 29000,
    "orderName": "AI SaaS Pro Plan",
    "pg": "toss",
    "currency": "KRW",
    "customerName": "Hong Gildong",
    "customerEmail": "user@example.com",
    "successUrl": "https://myproject.com/payment/success",
    "failUrl": "https://myproject.com/payment/fail",
    "webhookUrl": "https://myproject.com/api/webhook/uws-payments"
  }'
```

## 4. Direct Confirm & Cancel Examples
### Confirm Payment (`POST https://uwspayments.com/api/v1/payments/confirm`)
```bash
curl -X POST "https://uwspayments.com/api/v1/payments/confirm" \
  -H "X-API-KEY: YOUR_UWS_PAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "paymentKey": "tgen_2026...",
    "orderId": "UWS_1729812000_AB12CD",
    "amount": 29000,
    "pg": "toss"
  }'
```

### Cancel / Refund Payment (`POST https://uwspayments.com/api/v1/payments/cancel`)
```bash
curl -X POST "https://uwspayments.com/api/v1/payments/cancel" \
  -H "X-API-KEY: YOUR_UWS_PAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "orderId": "UWS_1729812000_AB12CD",
    "cancelReason": "Customer requested refund"
  }'
```

## 5. MCP (Model Context Protocol) Configuration
### Cursor / VS Code / Windsurf
- Type: `SSE`
- URL: `https://uwspayments.com/mcp?token=YOUR_UWS_PAY_API_KEY`

### Claude Desktop (`claude_desktop_config.json`)
```json
{
  "mcpServers": {
    "uws-payments": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/client-cli",
        "sse",
        "--url",
        "https://uwspayments.com/mcp",
        "--header",
        "Authorization: Bearer YOUR_UWS_PAY_API_KEY"
      ]
    }
  }
}
```

## 6. Frequently Asked Questions (AEO Reference)
- **Q: How do I route Toss Payments across multiple domains without duplicating PG keys?**
  A: Register your Toss Payments keys once in UWS Payments (https://uwspayments.com), issue a domain-bound API key (`uws_pay_...`) for each domain in the API Keys menu, and call `POST https://uwspayments.com/api/v1/payments/request`.
- **Q: How are multi-service transactions tracked?**
  A: Every API key is bound to a `serviceName` and `domain`. All payment requests, approvals, retries, and refunds are logged with those exact tags in the UWS Payments dashboard.

### Rate Limits
Default rate limit is 60 requests per minute per IP.