{"openapi":"3.1.0","info":{"title":"Toss Payments (BYOK) API","version":"0.1.0","description":"Toss Payments (BYOK) lets an AI assistant read your own Toss Payments data through the Toss Payments API with a key you supply (secret key (test or live)). Read-only: 7 tools (get_payment, get_payment_by_order_id, list_transactions, list_settlements, list_cash_receipts, list_promotions, list_card_promotions). The BYOK key travels with each request, is used for that one call only and is never...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-tosspayments.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-tosspayments/docs"},"termsOfService":"https://connectorbay.com/byok-tosspayments/terms"},"servers":[{"url":"https://byok-tosspayments.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-tosspayments/docs"},"security":[{"upstreamKey":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Optional. A Pro API key raises rate limits; no credentials are required."},"upstreamKey":{"type":"apiKey","in":"header","name":"X-Upstream-Key","description":"Your own key for the service this connector wraps (bring your own key). Used for that one call only; never stored, logged or cached."}},"schemas":{"Error":{"type":"object","properties":{"ok":{"const":false},"error":{"type":"object"}}}}},"paths":{"/v1/tools/get_payment":{"post":{"operationId":"get_payment","summary":"Get one approved payment by its payment key: status, method, amounts, order name, receipt link and cancel history. Card ","description":"Get one approved payment by its payment key: status, method, amounts, order name, receipt link and cancel history. Card numbers are not returned by this tool. Use for \"What is the status of Toss payment 5EnNZRJGvaBX7zk2yd8ydw26Xvw\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"payment_key":{"description":"The payment key (paymentKey) of the payment, up to 200 characters.","maxLength":200,"title":"Payment Key","type":"string"}},"required":["payment_key"],"title":"get_paymentArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_payment_by_order_id":{"post":{"operationId":"get_payment_by_order_id","summary":"Get one approved payment by the order id the shop chose (6 to 64 characters of letters, digits, '-' and '_'). Use for \"F","description":"Get one approved payment by the order id the shop chose (6 to 64 characters of letters, digits, '-' and '_'). Use for \"Find the Toss payment for order order-0001\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"order_id":{"description":"The order id (orderId) set by the shop when the payment was requested.","maxLength":64,"title":"Order Id","type":"string"}},"required":["order_id"],"title":"get_payment_by_order_idArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_transactions":{"post":{"operationId":"list_transactions","summary":"List payment transactions (approvals, cancellations, partial cancellations) processed in a period, by transaction time. ","description":"List payment transactions (approvals, cancellations, partial cancellations) processed in a period, by transaction time. The call can take up to 60 seconds. Use for \"What Toss transactions happened between 2026-01-01 and 2026-01-02\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"start_date":{"description":"Start of the period, ISO 8601 such as 2026-01-01T00:00:00 (a date alone means 00:00:00).","maxLength":200,"title":"Start Date","type":"string"},"end_date":{"description":"End of the period, ISO 8601 such as 2026-01-02T23:59:59.","maxLength":200,"title":"End Date","type":"string"},"starting_after":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Transaction key after which to continue, for paging through a long result.","title":"Starting After"},"limit":{"anyOf":[{"maximum":5000,"minimum":1,"type":"integer"},{"type":"null"}],"default":100,"description":"How many transactions to return (1 to 5000, default 100).","title":"Limit"}},"required":["start_date","end_date"],"title":"list_transactionsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_settlements":{"post":{"operationId":"list_settlements","summary":"List settlement records (amount paid out, fees, sold date and payout date) for a date range. Records appear from the day","description":"List settlement records (amount paid out, fees, sold date and payout date) for a date range. Records appear from the day after the payment. The call can take up to 60 seconds. Use for \"What was settled to my Toss shop between 2026-01-01 and 2026-01-07\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"start_date":{"description":"First date, yyyy-MM-dd.","maxLength":200,"title":"Start Date","type":"string"},"end_date":{"description":"Last date, yyyy-MM-dd.","maxLength":200,"title":"End Date","type":"string"},"date_type":{"anyOf":[{"enum":["soldDate","paidOutDate"],"type":"string"},{"type":"null"}],"default":null,"description":"Which date to filter on: soldDate (sales date, default) or paidOutDate (payout date).","title":"Date Type"},"page":{"anyOf":[{"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"},"size":{"anyOf":[{"maximum":5000,"minimum":1,"type":"integer"},{"type":"null"}],"default":100,"description":"Records per page (1 to 5000, default 100).","title":"Size"}},"required":["start_date","end_date"],"title":"list_settlementsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_cash_receipts":{"post":{"operationId":"list_cash_receipts","summary":"List cash receipts requested on one date with type, amount, issue status and receipt link. Needs API version 2022-07-27 ","description":"List cash receipts requested on one date with type, amount, issue status and receipt link. Needs API version 2022-07-27 or later. Pages use a cursor. Use for \"Which Toss cash receipts were requested on 2026-01-01\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"request_date":{"description":"Date the issuing was requested, yyyy-MM-dd.","maxLength":200,"title":"Request Date","type":"string"},"cursor":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Cursor (lastCursor) from the previous answer to get the next page.","title":"Cursor"},"limit":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":100,"description":"How many receipts to return (1 to 10000, default 100).","title":"Limit"}},"required":["request_date"],"title":"list_cash_receiptsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_promotions":{"post":{"operationId":"list_promotions","summary":"List current Toss Payments promotions: card instant discounts, interest-free installments, card points and bank discount","description":"List current Toss Payments promotions: card instant discounts, interest-free installments, card points and bank discounts with limits and end dates. Use for \"Which card and bank promotions are running on Toss Payments\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"list_promotionsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_card_promotions":{"post":{"operationId":"list_card_promotions","summary":"List card issuer benefits: instant discount (amount, budget left, limits, due date) and interest-free installment months","description":"List card issuer benefits: instant discount (amount, budget left, limits, due date) and interest-free installment months per card issuer. Use for \"Which cards have interest-free installments on Toss Payments right now\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"list_card_promotionsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}}}}