Authentication (Service & Domain Bound API Key)

When issuing an API key in the API Keys menu, you register the target Service Name and Domain. Every payment triggered with that API key automatically logs its associated service and domain in the UWS Payments ledger.

Header Name	Description
`X-API-KEY`	Your service & domain bound UWS Payments API key (e.g., `uws_pay_...`).

1. Request Payment Session (PG Router API)

Create a payment session for any external project using the Toss Payments (Single, Billing, PayPal) keys registered in UWS Payments. Redirect the user to the returned checkoutUrl to complete the payment.

POST /api/v1/payments/request

Request Body Parameters

Parameter	Type	Required	Description
`amount`	Number	Yes	Payment amount (e.g., `15000` for KRW or `20` for USD).
`orderName`	String	Yes	Order title displayed on the Toss checkout window (e.g., "Pro Plan Subscription").
`orderId`	String	No	Merchant order ID. Auto-generated if omitted.
`pg`	String	No	PG routing target: `toss` (Single Card), `toss_billing` (Billing Key), `toss_paypal` (PayPal USD).
`currency`	String	No	`KRW` (default) or `USD`.
`customerName`	String	No	Buyer name.
`customerEmail`	String	No	Buyer email address.
`successUrl`	String	No	External project URL to redirect upon payment completion.
`failUrl`	String	No	External project URL to redirect if payment fails or is canceled.
`webhookUrl`	String	No	Server-to-server webhook endpoint to receive `payment.completed` events.

cURL Example (Request Payment)

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",
       "customerName": "Hong Gildong",
       "customerEmail": "user@example.com",
       "successUrl": "https://myproject.com/payment/success",
       "failUrl": "https://myproject.com/payment/fail"
     }'

Python Example (Requests)

import requests

url = "https://uwspayments.com/api/v1/payments/request"
headers = {
    "X-API-KEY": "YOUR_UWS_PAY_API_KEY",
    "Content-Type": "application/json"
}
payload = {
    "amount": 29000,
    "orderName": "AI SaaS Pro Plan",
    "pg": "toss",
    "customerName": "Hong Gildong",
    "customerEmail": "user@example.com",
    "successUrl": "https://myproject.com/payment/success",
    "failUrl": "https://myproject.com/payment/fail"
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

Node.js / Frontend Example (Fetch & Open PG Window)

const response = await fetch('https://uwspayments.com/api/v1/payments/request', {
  method: 'POST',
  headers: {
    'X-API-KEY': 'YOUR_UWS_PAY_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    amount: 29000,
    orderName: 'AI SaaS Pro Plan',
    pg: 'toss', // 'toss' (단건) | 'toss_billing' (빌링) | 'toss_paypal' (페이팔 USD) | 'stripe'
    customerName: 'Hong Gildong',
    customerEmail: 'user@example.com',
    successUrl: 'https://myproject.com/payment/success',
    failUrl: 'https://myproject.com/payment/fail'
  })
});
const data = await response.json();
// 토스페이먼츠 SDK가 없어도 반환된 checkoutUrl로 이동하거나 팝업을 열면 즉시 PG 결제창이 실행됩니다!
window.location.href = data.checkoutUrl;

1-Line Browser SDK Example (토스 미구현 외부 사이트에서 팝업 PG창 즉시 호출)

<script src="https://uwspayments.com/sdk/uws-payments.js"></script>
<script>
  UwsPayments.requestPayment({
    apiKey: 'YOUR_UWS_PAY_API_KEY',
    amount: 29000,
    orderName: 'AI SaaS Pro Plan',
    pg: 'toss', // 'toss' | 'toss_billing' | 'toss_paypal' | 'stripe'
    mode: 'popup', // 'popup' (팝업 결제창) 또는 'redirect' (현재 창 이동)
    onSuccess: function(result) {
      console.log('결제 완료:', result.orderId, result.paymentKey);
    }
  });
</script>

2. Direct Confirm, Cancel & Order Status API

In addition to the hosted checkout router, you can confirm Toss payments directly from your backend, cancel/refund completed payments, or query real-time transaction status by orderId.

POST /api/v1/payments/confirm
POST /api/v1/payments/cancel
GET /api/v1/payments/:orderId

Direct Confirm Parameters (`POST /api/v1/payments/confirm`)

Parameter	Type	Required	Description
`paymentKey`	String	Yes	Toss Payments `paymentKey` received from the payment window.
`orderId`	String	Yes	Merchant order ID matching the payment request.
`amount`	Number	Yes	Exact payment amount to verify and confirm.
`orderName`	String	No	Order title to record in the UWS Payments unified log.
`pg`	String	No	`toss` (default) or `toss_paypal`.

Cancel / Refund Parameters (`POST /api/v1/payments/cancel`)

Parameter	Type	Required	Description
`orderId`	String	Yes*	Order ID to cancel (or provide `paymentKey`).
`paymentKey`	String	No	Toss `paymentKey` (optional if `orderId` is provided).
`cancelReason`	String	No	Reason for cancellation/refund (e.g., "Customer requested refund").

cURL Example (Cancel / Refund Payment)

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"
     }'

Rate Limits

The current API rate limit is set to 60 requests per minute per IP address. Exceeding this limit will result in a 429 Too Many Requests response.

Response Format & Webhook Payload

A successful payment session request returns a JSON object containing the session ID, order ID, bound service name & domain, selected PG provider, and the hosted checkoutUrl.

Response Schema (`POST /api/v1/payments/request`)

Field	Type	Description
`status`	String	`"success"` when the payment session is created.
`sessionId`	String	Unique UWS Payments checkout session ID.
`orderId`	String	Merchant order ID tracked across Toss Payments and UWS logs.
`orderName`	String	Order name displayed on the checkout screen.
`amount`	Number	Payment amount to be charged.
`currency`	String	Currency code (`KRW` or `USD`).
`pg`	String	Selected PG route (`toss`, `toss_billing`, `toss_paypal`).
`serviceName`	String	Service name bound to the API key.
`domain`	String	Domain bound to the API key.
`checkoutUrl`	String	Hosted checkout URL where the user completes payment.
`createdAt`	String (ISO Date)	Timestamp when the session was created.

Example Response

Loading...

Tool Name	Description
`create_payment_session`	Create a hosted checkout session (`checkoutUrl`) routed to Toss Payments (Single, Billing, or PayPal) bound to your API key's service and domain. Arguments: - `amount` (number, required): Payment amount (e.g., 29000 for KRW or 20 for USD). - `orderName` (string, required): Order title displayed on checkout. - `pg` (string, optional): PG target (`toss`, `toss_billing`, `toss_paypal`). - `currency` (string, optional): `KRW` or `USD`. - `customerName` (string, optional): Buyer name. - `customerEmail` (string, optional): Buyer email. - `successUrl` (string, optional): Redirect URL after successful payment. - `failUrl` (string, optional): Redirect URL on payment failure.
`get_payment_status`	Retrieve real-time payment status, amount, PG provider, and service/domain metadata by `orderId`. Arguments: - `orderId` (string, required): The order ID to look up.
`cancel_payment`	Cancel or refund a completed Toss payment using `orderId` or `paymentKey`. Arguments: - `orderId` (string, required): The order ID to cancel. - `cancelReason` (string, optional): Reason for refund/cancellation.

UWS Payments API & MCP Manual

Authentication (Service & Domain Bound API Key)

1. Request Payment Session (PG Router API)

Request Body Parameters

cURL Example (Request Payment)

Python Example (Requests)

Node.js / Frontend Example (Fetch & Open PG Window)

1-Line Browser SDK Example (토스 미구현 외부 사이트에서 팝업 PG창 즉시 호출)

2. Direct Confirm, Cancel & Order Status API

Direct Confirm Parameters (`POST /api/v1/payments/confirm`)

Cancel / Refund Parameters (`POST /api/v1/payments/cancel`)

cURL Example (Cancel / Refund Payment)

Rate Limits

Response Format & Webhook Payload

Response Schema (`POST /api/v1/payments/request`)

Example Response

Model Context Protocol (MCP) Server

Prerequisites

Connecting to the Hosted Server

Claude Desktop Configuration (`claude_desktop_config.json`)

Cursor / VS Code / Windsurf

Available Tools

UWS Payments API & MCP Manual

Authentication (Service & Domain Bound API Key)

1. Request Payment Session (PG Router API)

Request Body Parameters

cURL Example (Request Payment)

Python Example (Requests)

Node.js / Frontend Example (Fetch & Open PG Window)

1-Line Browser SDK Example (토스 미구현 외부 사이트에서 팝업 PG창 즉시 호출)

2. Direct Confirm, Cancel & Order Status API

Direct Confirm Parameters (POST /api/v1/payments/confirm)

Cancel / Refund Parameters (POST /api/v1/payments/cancel)

cURL Example (Cancel / Refund Payment)

Rate Limits

Response Format & Webhook Payload

Response Schema (POST /api/v1/payments/request)

Example Response

Model Context Protocol (MCP) Server

Prerequisites

Connecting to the Hosted Server

Claude Desktop Configuration (claude_desktop_config.json)

Cursor / VS Code / Windsurf

Available Tools

Sign In

Direct Confirm Parameters (`POST /api/v1/payments/confirm`)

Cancel / Refund Parameters (`POST /api/v1/payments/cancel`)

Response Schema (`POST /api/v1/payments/request`)

Claude Desktop Configuration (`claude_desktop_config.json`)