Toss Payments API
★ Only Publicly Available OpenAPI DocumentPaymentsPayment Processingbasic7 EndpointsREST
For Agents
Confirm, retrieve, and cancel Korean card, virtual account, and mobile payments through Toss Payments, plus mint billing keys for recurring charges.
Use for: I need to confirm a Toss Payments transaction after the buyer approves, Retrieve a Toss payment by its paymentKey, Cancel a Toss payment and refund the buyer, Find a Toss payment by my orderId
Not supported: 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.
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.
Install Jentic One Beta
Connect the Toss Payments API to your agent
Jentic One is a self-hosted execution layer for AI agents. It lets your agent call the Toss Payments API, or any other public or private API you need. You set the rules, the agent never sees your credentials, and every call is logged.
Two steps, two machines. Install the instance in a safe environment, then register your agent from wherever it runs.
1
Step 1: Jentic One Host machine
# On the machine that will host your Jentic One instance:
curl -fsSL "https://jentic.com/install.sh?src=apis&api=%2Fapis%2Fapi.tosspayments.com%2Ftosspayments" | sh2
Step 2: Agent machine
# On the machine where your agent runs (keep this separate from the instance):
curl -fsSL "https://jentic.com/install.sh?src=apis&api=%2Fapis%2Fapi.tosspayments.com%2Ftosspayments" | sh
jentic register # connects your agent to your Jentic One instanceJentic One is in public beta. The setup above keeps your agent separate from the instance, which is what you want before using real credentials: an agent running as the same OS user as Jentic One can read its stored keys directly. Just evaluating? A single local install is fine to start. See the secure deployment guide for the tiers.
Capabilities
What an agent can do with Toss Payments API.
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
Patterns agents use Toss Payments API for, with concrete tasks.
★ 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.
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.
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.
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.
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.
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
7 endpoints — jentic publishes the only available openapi specification for toss payments api, keeping it validated and agent-ready.
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
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
Why Jentic?
What agents get from Jentic-routed access to this vendor.
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 isolation
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.
Intent-based discovery
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
Alternatives and complements available in the Jentic catalogue.
Alternative
Stripe
Stripe is a global payments alternative with broader currency coverage but weaker presence in Korean local methods.
Pick Stripe for global card processing; choose Toss when local Korean methods like Toss in-app and KR virtual accounts are required.
FAQs
Specific to using Toss Payments API through Jentic.
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.
GET STARTED