LLM Quick Reference

This page is optimized for AI agents: use it for routing and guardrails, then jump to the linked guide/reference for implementation details.

Page scope: flow model + decision rules + entry points + pitfalls + routing. Full code and details live in guide/reference pages.

Companion resource: When this page is insufficient, consult llms.txt first — the complete Toss Payments docs index in LLM-standard format. Use it to locate the precise guide/reference page for any topic not fully covered here.

Markdown source for any docs page: Append .md to any docs URL to fetch the raw markdown (more token-efficient than HTML; tabbed content is fully exposed). Examples: /reference.md, /guides/v2/payment-widget.md.

Recommended sequence when using this page:

1. Read this page to build the mental model.
2. Determine: SDK version → product → payment scenario.
3. For details beyond this page, consult llms.txt → navigate to the precise guide/reference page.
4. Generate implementation code.
5. Validate against §8 Common Mistakes before finalizing.

• Prefer V2 SDK unless the user specifies V1 or shows existing V1 code.
• Prefer the checkout-page type when no specific UI/scenario keyword is given.
• Ask a brief clarification question only when ambiguity affects architecture (e.g., recurring vs one-time, custom UI vs default). Do not ask for cosmetic choices.

Toss Payments uses 3 actors: Client (browser) / Merchant Server / Toss Payments. The diagram below shows the basic flow for one-time payments (card, transfer, easy pay). Virtual account and auto-billing are variations of this flow.

In short:

1. Client requests payment authentication via SDK → user authenticates at Toss Payments.
2. Server confirms the authenticated payment with the secret key, then saves the result.

Responsibility split:

Scenario variations:

• One-time payment (card / transfer / easy pay): Flow above as is.
• Virtual account: Step 3 only issues an account number. Payment is finalized asynchronously via DEPOSIT_CALLBACK webhook after deposit.
• Auto-billing: Billing key issuance (SDK method — variation of steps 2~4 / API method — server-only, separate contract required) → server calls billing endpoint for recurring payments.

4 mandatory rules before integration. Violation leads to security incidents, payment tampering, or hallucinated code.

For key types and issuance, see API Keys Guide.

requestPayment runs in the client JS SDK, so a user can modify amount arbitrarily from the browser console. (e.g., the order shows 50,000 KRW but the console call is changed to amount: 100.) Authentication completes with the modified amount and the browser redirects via successUrl. If the merchant passes that value to the confirm API without verification, the payment completes at the tampered amount.

(Modifying the successUrl query string directly is blocked by the confirm API since it differs from the authenticated amount. The threat is tampering before authentication.)

Verify in the server that amount from successUrl matches the merchant's intended amount at request time before calling the Payment Confirmation API.

Append a single colon to the secret key, then base64-encode. Missing colon is the most common mistake.

• The password slot after the colon is empty (hence trailing colon).
• If UTF-8 BOM is present, the result starts with 77u/. Re-encode without BOM.

For details, see Authorization Header.

LLMs frequently hallucinate undocumented or deprecated fields when generating PG integration code. Use only fields defined in this page or in the linked SDK/API docs. If a field is not documented here or in linked docs, do not generate it.

• Do not infer field names from other PG vendors (e.g., Stripe's payment_intent, KCP, INICIS).
• Do not generate fields based on naming patterns alone (e.g., guessing payment_method_id when only method is documented).
• If a needed field is unclear, consult llms.txt → exact page, or ask the user. Do not guess.

• V2 by default — If user does not specify V1, use V2.
• Do not mix V1 and V2 — Common mistake: calling V2 methods on V1 SDK URL.
• If existing code is V1, confirm with user before keeping V1.

Toss Payments SDK hierarchy:

SDK version is independent of API version — both V1 and V2 SDKs use api.tosspayments.com/v1/*.

V2 SDK initialization and product methods:

widgets() covers two types that differ only in the render method. payment() is the legacy payment-window SDK, also used to open a card company's own window.

For differences, see Migration Guide.

1. If the user specifies a product, use it.
2. If not specified, branch by user requirement keyword (table below).
3. If no keyword matches, proceed with the checkout-page type (default). Add a note at the end of the response: "If you want the payment UI in a popup window instead of the order page, switch to the payment-window type."
4. If keywords match two or more products, briefly confirm with the user.

When searching docs, use the Korean name. The English type names exist only inside this page. Guide pages are written in Korean and the search index matches on substrings, so an English type name returns nothing — query 주문서형 결제, not checkout-page type.

The legacy payment window / 결제창(구버전) — tossPayments.payment() with its own guide — still exists for merchants integrated before the current types. Do not choose it for a new integration unless the user explicitly asks for it.

For full comparison, see Payment Products Comparison.

Docs, blog posts, and LLM training data written before the 2026 renaming use old product names. Map them to the current products:

When the user says "결제위젯" or "통합결제창", treat it as the mapped current product and mention that the name changed.

All three are payment-window types and all are current V2. They differ in where the window appears — embedded in the order page, opened as a popup, or handed off to the card company's own app.

• Checkout-page type (주문서형 결제) — SDK renders the payment method UI inside the order page. Merchant provides container divs. widgets() → setAmount() → renderPaymentMethods() → renderAgreement() → buyer clicks pay → requestPayment()
• Payment-window type (결제창형 결제) — SDK renders an entry that opens the payment window as a popup. widgets() → setAmount() → renderPaymentWindow() → paymentRequest event → requestPayment()
• Direct type (자체창) — Opens the card company's or easy-pay app's own window directly. There is no dedicated SDK; it runs on the legacy payment-window SDK. payment() → requestPayment({ card: { flowMode: "DIRECT" } })

The first two share tossPayments.widgets() and differ only in the render method. Only the direct type uses tossPayments.payment().

If no specific clue, choose the checkout-page type.

Each scenario's V2 entry point, flow, and full-code routing. Look up full code in the guide pages — this page provides entry points only.

Used across all scenarios. Do not fill arbitrarily — follow format constraints.

amount.currency is "KRW" for domestic payments. Overseas easy pay (PayPal) supports "USD" only. amount.value is an integer for KRW (no decimals).

After client requestPayment, the auth result redirects to one of these URLs. Branch in merchant server.

• successUrl query string (auth success): paymentKey, orderId, amount (the checkout-page type also includes paymentType) → verify amount (Critical 2.2) → call confirm API.
• failUrl query string (auth failure / user cancellation): code, message, orderId → do not call confirm API. Show a user-friendly message based on code, then offer a retry path (e.g., back to checkout). Do not auto-redirect to a generic error page — that loses context. For codes, see SDK Error Codes.

Scenarios 5.A·5.B·5.C require calling the confirm API on the server after the client payment request to finalize. 5.D (billing) and 5.E (cancel) are separate flows.

Use the merchant's intended amount at request time for amount, not the successUrl query (Critical 2.2).

• Entry point: tossPayments.widgets({ customerKey })
• Flow: setAmount({ value, currency: "KRW" }) → renderPaymentMethods → renderAgreement → requestPayment({ orderId, orderName, successUrl, failUrl }) → successUrl → server confirm
• Key: SDK auto-renders payment method/agreement UI inside the order page. Merchant only provides container divs.
• Full code: Checkout-page type Guide, SDK Reference

Canonical flow (baseline pattern for any one-time payment — use this as the default mental model):

• Entry point: tossPayments.widgets({ customerKey }) — same as 5.A; only the render method differs
• Flow: setAmount({ value, currency: "KRW" }) → renderPaymentWindow → paymentRequest event → requestPayment → successUrl → server confirm
• Key: SDK renders an entry that opens the payment window as a popup instead of embedding the UI in the order page.
• Full code: Payment-window type Guide, SDK Reference

Legacy payment window — merchants integrated before the current types call tossPayments.payment({ customerKey }).requestPayment({ method, amount: { value, currency: "KRW" }, orderId, orderName, successUrl, failUrl, ... }) in a single client call and branch by method (CARD, VIRTUAL_ACCOUNT, TRANSFER, MOBILE_PHONE, EASY_PAY, CULTURE_GIFT_CERTIFICATE, etc.). Scenario 5.C and the direct type run on this SDK. Guide: legacy payment window, SDK Reference. Do not pick it for a new integration.

• Entry point: tossPayments.payment().requestPayment({ method: "VIRTUAL_ACCOUNT", amount: { value, currency: "KRW" }, virtualAccount, orderId, orderName, successUrl, failUrl, customerEmail?, customerName?, customerMobilePhone? })
• virtualAccount fields: One of validHours or dueDate is required. cashReceipt, escrowProducts are optional.
• Customer info: customerEmail/customerName/customerMobilePhone are optional in SDK but practically needed for deposit notification and refund. Recommended to collect.
• Flow: Issue → confirm API call (response status: WAITING_FOR_DEPOSIT) → wait for deposit → DEPOSIT_CALLBACK webhook → query API → confirm status: DONE → mark as completed
• Key: Request time ≠ completion time. Do not mark as completed on issue response. DEPOSIT_CALLBACK webhook handling required.
• Full code: Virtual Account Glossary, Webhook Events

Billing key issuance → server calls billing endpoint for recurring payments. Two methods for billing key issuance.

SDK method (default):

• Step 1 (client): payment.requestBillingAuth({ method: "CARD" }) → successUrl receives customerKey, authKey
• Step 2 (server): POST /v1/billing/authorizations/issue (authKey → billingKey)
• Step 3 (server): POST /v1/billing/{billingKey} (recurring payment)

API method (separate contract required — non-authenticated payment qualification + PCI-DSS):

• Server: POST /v1/billing/authorizations/card (card info directly) → billingKey
• Recurring payment with billing key is the same as SDK step 3

Key: Billing key payment does NOT use requestPayment/successUrl//v1/payments/confirm flow. Server-only.

Full code: Auto-billing Guide, Billing API

• Cancel: POST /v1/payments/{paymentKey}/cancel + { cancelReason }
• Partial cancel: Add cancelAmount to body
• Virtual account refund: Add refundReceiveAccount (bank/account number/holder name) to body
• Query: GET /v1/payments/{paymentKey} or GET /v1/payments/orders/{orderId}
• Full code: Cancel API, Query API

Even after the scenario (5.A~5.E) is set, each payment method has caveats. Flow mapping is in section 5; this section is pitfalls only.

Key terms:

• Transaction — Each approve/cancel/partial-cancel from a payment is a "transaction". Identified by transactionKey.
• Settlement — Paid out by transaction date + business day. General/scheduled settlement.

For payment method policies: Card, Virtual Account, Transfer, Easy Pay, Non-auth Payment, Auto-billing, Transaction, Settlement.

• Available on all POST APIs (GET ignored).
• Max 300 chars, UUID v4 recommended.
• Valid for 15 days from first request.
• Same idempotency key returns the first response (prevents duplicate payments).

For details, see Auth & Headers.

For details, see Webhook Events.

• Test environment: Key prefix test_*. No real deposit. Virtual account number prefixed with X. KakaoPay/Payco have separate policies.
• Live environment: Key prefix live_*. Real deposits.

For details, see Environment Setup.

Frequently wrong patterns when LLMs generate Toss Payments code.

Scenario-specific full-code routing is in section 5 (entry points). This section is for meta/operations/reference information beyond scenarios.