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 Payment Widget 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:

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 Payment Widget (default). Add a note at the end of the response: "If you want to build the payment method UI yourself, switch to Standard Payment Window."
4. If keywords match two or more products, briefly confirm with the user.

For full comparison, see Payment Products Comparison.

The essence is who renders the payment method selection UI:

• Payment Widget — SDK auto-renders. Merchant only provides a <div id="payment-methods" /> container.
• Standard Payment Window — Merchant builds payment method selection UI directly → user-selected method passed to requestPayment({ method: "CARD" }). The variation where the merchant fully customizes the UI is Custom Payment Window (code pattern same as Standard).

If no specific clue, choose Payment Widget.

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.value is always integer (no decimal in KRW). amount.currency is "KRW" (only KRW supported in V2 standard scope).

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

• successUrl query string (auth success): paymentKey, orderId, amount (Payment Widget 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. Merchant only provides container divs.
• Full code: Payment Widget Guide, V2 SDK Reference

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

• Entry point: tossPayments.payment({ customerKey }).requestPayment({ method, amount: { value, currency: "KRW" }, orderId, orderName, successUrl, failUrl, ... })
• Flow: Single client call → payment window → successUrl → server confirm
• Key: Merchant builds payment method selection UI. Branch by method (CARD, VIRTUAL_ACCOUNT, TRANSFER, MOBILE_PHONE, EASY_PAY, CULTURE_GIFT_CERTIFICATE, etc.)
• Full code: Payment Window Guide

• 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.