canonical: https://jentic.com/apis/api.tosspayments.com/tosspayments # Toss Payments API Jentic publishes the only available OpenAPI specification for Toss Payments API, keeping it validated and agent-ready. Toss Payments processes payments for Korean buyers across cards, virtual accounts, and mobile payment methods. The API exposes the full lifecycle: create a payment, confirm it after the buyer authorises in their Toss app, retrieve the payment record, cancel a successful payment, and issue billing keys for recurring charges. Use it when an ecommerce flow needs to settle KRW payments through Toss. ## For AI agents Confirm, retrieve, and cancel Korean card, virtual account, and mobile payments through Toss Payments, plus mint billing keys for recurring charges. ## Scope Does not handle in-app buyer authorisation UI, payout to merchant bank accounts, or accounting reconciliation - use for confirming, retrieving, cancelling, and recurring-charging Korean payments only. ## Capabilities - Confirm a payment that the buyer just authorised inside the Toss app and capture the funds - Retrieve a payment by paymentKey to verify the latest status and method-specific receipt fields - Cancel a successful payment and trigger a refund to the buyer's original method - Look up a payment by the merchant's own orderId for cross-system reconciliation - Mint a billing key for card-on-file recurring charges through the billing-authorisations endpoint - Charge a stored billing key for a follow-on subscription period without re-prompting the buyer ## Use cases ### Korean Ecommerce Checkout Confirmation A Korean storefront initiates a Toss Payments charge in the buyer's app, then waits for the merchant server to confirm the transaction. The agent posts the paymentKey and amount to /v1/payments/confirm, and Toss settles the charge. The same endpoint covers cards, virtual accounts, and mobile methods. Example prompt: POST to /v1/payments/confirm with paymentKey, orderId, and amount to settle the buyer's authorised transaction ### Order Reconciliation by Merchant Order ID A finance team reconciling sales against bank deposits needs to look up Toss payments by the merchant's own orderId rather than Toss's paymentKey. /v1/payments/orders/{orderId} returns the payment record with method-specific fields, so reconciliation can proceed without storing the Toss paymentKey alongside every order. Example prompt: GET /v1/payments/orders/{orderId} for each merchant order in the day's batch and reconcile to the deposit ledger ### Customer-Initiated Refund Workflow When a buyer requests a refund within the return window, an agent finds the payment by orderId, then cancels it via /v1/payments/{paymentKey}/cancel. The cancellation reaches the buyer's card or virtual account through Toss without the merchant interacting with the underlying issuer. Refund status is reflected in the returned payment object. Example prompt: Look up the payment by orderId, then POST /v1/payments/{paymentKey}/cancel with the cancellation reason and amount ### Recurring Subscription Billing A SaaS company wants to charge Korean subscribers monthly without re-prompting them. The first transaction issues a billing key via /v1/billing/authorizations/card; each subsequent month, an agent calls /v1/billing/{billingKey} to charge the next period. The billing key is the durable handle that replaces card-on-file storage on the merchant side. Example prompt: Issue a billing key on first charge, store the billingKey, and POST to /v1/billing/{billingKey} for each future renewal ### AI Agent Payment Confirmation via Jentic An AI agent processing checkouts uses Jentic to find the right Toss operation by intent. After the buyer authorises in the Toss app, the agent calls Jentic with 'confirm a toss payment', loads the schema, executes the call with the paymentKey and amount, and reports back to the merchant. Example prompt: Use Jentic to find the Toss confirm-payment operation, execute it with paymentKey, orderId, and amount, and verify the resulting status is DONE ## Key endpoints | Method | Path | Description | | --- | --- | --- | | POST | /v1/payments | Create a payment record | | POST | /v1/payments/confirm | Confirm an authorised payment | | GET | /v1/payments/{paymentKey} | Retrieve a payment by paymentKey | | POST | /v1/payments/{paymentKey}/cancel | Cancel a payment and refund the buyer | | GET | /v1/payments/orders/{orderId} | Look up a payment by merchant orderId | | POST | /v1/billing/authorizations/card | Issue a recurring-billing key | | POST | /v1/billing/{billingKey} | Charge a stored billing key | ## Key resources - **Payments** — One-time payment confirmation, retrieval, and cancellation - **Orders** — Lookup payments by merchant order id - **Billing Keys** — Issue and charge stored billing keys for recurring charges ## Why Jentic - **Setup:** Wiring Toss Payments by hand means setting up its basic auth with your secret key, learning the payment and billing resource shapes, and handling confirm and cancel flows yourself. Through Jentic you install once, import Toss Payments from the API Directory, store the secret key once, and your agent calls it. - **Permission scoping:** Toss Payments puts the payment key in the URL path (/payments/{paymentKey}/...), so a rule can pin your agent to one payment: it can retrieve that payment and nothing else. You choose the operations it may call, so cancelling a payment is not included unless you add it. - **Credential handling:** Your Toss Payments secret key is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context. - **Discovery method:** Agents search Jentic by intent such as 'confirm a payment' or 'look up a payment by order id', and Jentic returns the matching Toss Payments operation with its input schema so the agent calls the right endpoint without browsing the reference docs. ## Related APIs - **Stripe** — Stripe is a global payments alternative with broader currency coverage but weaker presence in Korean local methods. - **Adyen Checkout** — Adyen's checkout supports many local Korean methods alongside global cards. - **Kakao** — Kakao surfaces login, identity, and KakaoPay flows that often sit alongside Toss in Korean checkouts. ## FAQ ### Why is there no official OpenAPI spec for Toss Payments? Toss Payments does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call Toss Payments API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer. ### What authentication does the Toss Payments API use? Toss Payments uses HTTP basic authentication. The merchant secret key is sent as the basic-auth username with an empty password, base64-encoded in the Authorization header. When called through Jentic, the secret key is held in the Jentic credential vault and injected at execution time. ### Can I issue a refund with the Toss Payments API? Yes. POST /v1/payments/{paymentKey}/cancel with the cancellation reason and the cancel amount. Toss handles the refund back to the buyer's card, virtual account, or mobile method. The returned payment object reflects the new cancellation state. ### What are the rate limits for the Toss Payments API? The spec does not declare specific numeric rate limits; Toss enforces fair-use throttling at the platform layer. Build retries with exponential backoff for 429 responses, and avoid polling /v1/payments/{paymentKey} more than necessary - webhooks are preferred for status updates. ### How do I confirm a Toss payment through Jentic? Install the SDK with `pip install jentic`. Search Jentic for `confirm a toss payment`, load the schema for POST /v1/payments/confirm, and execute it with paymentKey, orderId, and amount. Jentic injects the basic-auth credential and returns the confirmed payment. ### Does the API support recurring payments? Yes. Mint a billing key with POST /v1/billing/authorizations/card, then charge the same key on each renewal with POST /v1/billing/{billingKey}. The billing key replaces direct card-on-file storage on the merchant side. ### Can I limit what my agent is allowed to do with the Toss Payments API? Yes. Because you run Jentic One yourself, your own rules decide which Toss Payments operations and credentials the agent may use. Since Toss puts the payment key in the URL path, such as /v1/payments/{paymentKey}/cancel, you can pin the agent to a single payment so it only retrieves that record and nothing else. You also choose the operations it may call, so cancelling a payment or minting a billing key is not available to the agent unless you explicitly grant it.