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.

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" | sh

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 instance

Jentic 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

GET STARTED

Start building with Toss Payments API

Explore with Jentic One

View OpenAPI Document

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.

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.

Toss Payments API

AI ReadinessFoundational (D-)41/100

See full scorecard

Agent-ready OpenAPI document · curated by JenticPaymentsPayment Processingbasic7 EndpointsREST

Know of an official OpenAPI document? Contribute it →

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.

Jentic One on Github View OpenAPI Document

Show dimension breakdown

100

Foundational Compliance

Base layer of spec validity and structural soundness.

Grade: A+Signals: 4

99%

Lint Results

Aggregated quality score from linter diagnostics, weighted by severity.

100%

Resolution Completeness

Percentage of `$ref` references that resolve successfully.

100%

Specification Validity

Checks whether the API description parses successfully and conforms to its declared specification (e.g., OpenAPI).

100%

Structural Integrity

Structural correctness score based on schema issues using logarithmic dampening.

Developer Experience & Jentic Compatibility

Clarity, completeness, and ingestion readiness for developers and tooling.

Grade: B-Signals: 4

Example Density

How richly the API is illustrated with examples.

100%

Example Validity

Percentage of examples that conform to their schemas.

50%

Response Coverage

Percentage of operations with complete response definitions (success, client error, server error).

100%

Tooling Readiness

Health of API ingestion, bundling, and resolution within Jentic pipelines.

AI-Readiness & Agent Experience

Semantic breadth, depth, and agent comprehension for AI systems.

Grade: D+Signals: 4

40%

Description Coverage

Coverage of descriptions across API elements.

Error Standardization

Coverage of RFC 9457 Problem Details for error responses.

100%

OperationId Quality

Coverage, uniqueness, and casing consistency of operationIds for AI inference.

50%

Summary Coverage

Coverage of summaries across operations/tags/info.

Agent Usability

Functional utility, complexity comfort, and AI orchestration readiness.

Grade: A+Signals: 1

94%

Complexity Comfort

Agent comfort level based on API operational and structural complexity.

Security

Trust, risk posture, and security compliance.

Grade: FSignals: 1

10%

Authentication Strength

Average quality of security schemes based on authentication method strength (weakest link for OAuth2).

100

AI Discoverability

Findability, semantic richness, and reasoning readiness.

Grade: A+Signals: 1

100%

Descriptive Richness

Clarity and depth of descriptions across API elements.

Connect the Toss Payments API to your agent

Capabilities

Start building with Toss Payments API

Use Cases

Key Endpoints

Why Jentic?

Related APIs

FAQs

Toss Payments API

Jentic AI Readiness Score

Toss Payments API

Foundational Compliance

Lint Results

Resolution Completeness

Specification Validity

Structural Integrity

Developer Experience & Jentic Compatibility

Example Density

Example Validity

Response Coverage

Tooling Readiness

AI-Readiness & Agent Experience

Description Coverage

Error Standardization

OperationId Quality

Summary Coverage

Agent Usability

Complexity Comfort

Security

Authentication Strength

AI Discoverability

Descriptive Richness