bldinit Toss Rest API

The toss-rest API from bldinit — 9 operation(s) for toss-rest.

GitHub OpenAPI

Operations 10

POST /api/v1/toss/v1/payments/confirm Confirm and approve a payment after SDK authentication #
GET /api/v1/toss/v1/payments/{paymentKey} Fetch a payment by paymentKey #
GET /api/v1/toss/v1/payments/orders/{orderId} Fetch a payment by your own orderId #
POST /api/v1/toss/v1/payments/{paymentKey}/cancel Cancel a payment — full or partial refund #
POST /api/v1/toss/v1/virtual-accounts Issue a virtual account for bank-transfer payment #
GET /api/v1/toss/v1/transactions List transactions (approvals + cancellations) by date range #
GET /api/v1/toss/v1/settlements List settlement records by date range #
POST /api/v1/toss/v1/cash-receipts Issue a cash receipt for a non-card payment #
GET /api/v1/toss/v1/cash-receipts List cash receipts issued on a given date #
POST /api/v1/toss/v1/cash-receipts/{receiptKey}/cancel Cancel a previously-issued cash receipt #

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API
curl "https://apis.io/api/v1/apis/mcpweave-com:mcpweave-com-toss-rest-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"

Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. By signing up you are subscribing to the APIs.io and API Evangelist newsletters — you can unsubscribe from any issue. See our Privacy Policy and Terms.

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

mcpweave-com-toss-rest-api-openapi.yml Raw ↑
openapi: 3.2.0
info:
  title: mcpweave Toss Rest API
  description: Asia-native MCP Gateway — Native pass-through, FastMCP, Paddle+Toss billing
  version: '2026-04-27'
tags:
- name: toss-rest
paths:
  /api/v1/toss/v1/payments/confirm:
    post:
      tags:
      - toss-rest
      summary: Confirm and approve a payment after SDK authentication
      description: 'Final server-side approval step. The browser SDK has authenticated

        the buyer and returned `paymentKey` + `orderId` + `amount`; this

        endpoint locks the approval in. **Critical**: verify the

        `amount` against your order total *before* calling — Toss does

        not validate that the amount matches what was originally

        requested in `requestPayment()`.


        Idempotent via the `Idempotency-Key` header (Toss native, 15

        days). Response is the full Payment object with status `DONE`.


        **Sandbox error simulation**: with a `test_sk_*` key, append a

        `TossPayments-Test-Code` HTTP header (e.g. `REJECT_CARD_PAYMENT`,

        `INVALID_CARD_NUMBER`, `EXCEED_MAX_AMOUNT`) to reproduce the

        full set of production error codes during dogfood. Live keys

        ignore the header. Reference:

        https://docs.tosspayments.com/guides/v2/get-started/environment


        Source: https://docs.tosspayments.com/reference#결제-승인'
      operationId: toss_confirm_payment
      parameters:
      - name: connection_id
        in: query
        required: true
        schema:
          type: string
          description: mcpweave connection_id
          title: Connection Id
        description: mcpweave connection_id
      - name: confirmation_token
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: 'ADR-030: required for irreversible op. First call returns token.'
          title: Confirmation Token
        description: 'ADR-030: required for irreversible op. First call returns token.'
      - name: X-API-Key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Api-Key
      - name: mcpweave_session
        in: cookie
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Mcpweave Session
      requestBody:
        content:
          application/json:
            schema:
              anyOf:
              - type: object
                additionalProperties: true
              - type: 'null'
              title: Body
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        default:
          description: Native cafe24 response (200) or gateway error envelope (4xx/5xx)
  /api/v1/toss/v1/payments/{paymentKey}:
    get:
      tags:
      - toss-rest
      summary: Fetch a payment by paymentKey
      description: 'Returns the full Payment object — current status (READY,

        IN_PROGRESS, WAITING_FOR_DEPOSIT, DONE, CANCELED, PARTIAL_CANCELED,

        ABORTED, EXPIRED), method (카드, 가상계좌, 계좌이체, 휴대폰,

        간편결제), card / virtualAccount / transfer / mobilePhone /

        easyPay sub-objects depending on method, and the `cancels` array

        if any cancellations happened.


        Source: https://docs.tosspayments.com/reference#paymentkey로-결제-조회'
      operationId: toss_get_payment
      parameters:
      - name: paymentKey
        in: path
        required: true
        schema:
          type: string
          title: Paymentkey
      - name: connection_id
        in: query
        required: true
        schema:
          type: string
          description: mcpweave connection_id
          title: Connection Id
        description: mcpweave connection_id
      - name: X-API-Key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Api-Key
      - name: mcpweave_session
        in: cookie
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Mcpweave Session
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        default:
          description: Native cafe24 response (200) or gateway error envelope (4xx/5xx)
  /api/v1/toss/v1/payments/orders/{orderId}:
    get:
      tags:
      - toss-rest
      summary: Fetch a payment by your own orderId
      description: 'Same response shape as `toss_get_payment` but keyed off the

        merchant-side `orderId`. Useful when reconciling against your

        order DB without persisting Toss''s `paymentKey` separately.


        Source: https://docs.tosspayments.com/reference#orderid로-결제-조회'
      operationId: toss_get_payment_by_order_id
      parameters:
      - name: orderId
        in: path
        required: true
        schema:
          type: string
          title: Orderid
      - name: connection_id
        in: query
        required: true
        schema:
          type: string
          description: mcpweave connection_id
          title: Connection Id
        description: mcpweave connection_id
      - name: X-API-Key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Api-Key
      - name: mcpweave_session
        in: cookie
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Mcpweave Session
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        default:
          description: Native cafe24 response (200) or gateway error envelope (4xx/5xx)
  /api/v1/toss/v1/payments/{paymentKey}/cancel:
    post:
      tags:
      - toss-rest
      summary: Cancel a payment — full or partial refund
      description: 'Cancels an approved payment. Without `cancelAmount` this is a

        full cancellation; supply `cancelAmount` for partial refunds

        (e.g. one item out of many). Repeated partial cancels collapse

        into the response `cancels` array — the merchant''s order DB

        should mirror that array, not assume single-cancel.


        **Virtual account refunds**: if the original method is

        `가상계좌` and the buyer has already deposited, supply

        `refundReceiveAccount` with the buyer''s bank + account number +

        holder name. Toss credits that account on cancel-day + 2 banking

        days. Pre-deposit virtual accounts cancel without

        `refundReceiveAccount` (no money to return).


        Idempotent via `Idempotency-Key` header (15 day window).


        Source: https://docs.tosspayments.com/guides/v2/cancel-payment'
      operationId: toss_cancel_payment
      parameters:
      - name: paymentKey
        in: path
        required: true
        schema:
          type: string
          title: Paymentkey
      - name: connection_id
        in: query
        required: true
        schema:
          type: string
          description: mcpweave connection_id
          title: Connection Id
        description: mcpweave connection_id
      - name: confirmation_token
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: 'ADR-030: required for irreversible op. First call returns token.'
          title: Confirmation Token
        description: 'ADR-030: required for irreversible op. First call returns token.'
      - name: X-API-Key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Api-Key
      - name: mcpweave_session
        in: cookie
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Mcpweave Session
      requestBody:
        content:
          application/json:
            schema:
              anyOf:
              - type: object
                additionalProperties: true
              - type: 'null'
              title: Body
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        default:
          description: Native cafe24 response (200) or gateway error envelope (4xx/5xx)
  /api/v1/toss/v1/virtual-accounts:
    post:
      tags:
      - toss-rest
      summary: Issue a virtual account for bank-transfer payment
      description: 'Issues a virtual account up front (without going through the

        browser SDK). Most merchants use the SDK flow instead; this

        endpoint is for back-office bank-transfer scenarios — for

        example, a sales-team-assisted order where the buyer pays via

        wire transfer to a generated account number.


        Response includes the account number, bank name, and

        `dueDate` (default 7 days). Toss notifies via webhook when the

        buyer deposits.


        Source: https://docs.tosspayments.com/reference#가상계좌-발급-요청'
      operationId: toss_issue_virtual_account
      parameters:
      - name: connection_id
        in: query
        required: true
        schema:
          type: string
          description: mcpweave connection_id
          title: Connection Id
        description: mcpweave connection_id
      - name: confirmation_token
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: 'ADR-030: required for irreversible op. First call returns token.'
          title: Confirmation Token
        description: 'ADR-030: required for irreversible op. First call returns token.'
      - name: X-API-Key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Api-Key
      - name: mcpweave_session
        in: cookie
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Mcpweave Session
      requestBody:
        content:
          application/json:
            schema:
              anyOf:
              - type: object
                additionalProperties: true
              - type: 'null'
              title: Body
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        default:
          description: Native cafe24 response (200) or gateway error envelope (4xx/5xx)
  /api/v1/toss/v1/transactions:
    get:
      tags:
      - toss-rest
      summary: List transactions (approvals + cancellations) by date range
      description: 'Iterates all transactions — approvals and cancellations — in

        the given date range. Use this for daily accounting

        reconciliation, not for live order lookup (which should use

        toss_get_payment / toss_get_payment_by_order_id instead).


        Pagination via `startingAfter` cursor — supply the last

        transactionKey from the previous page to continue. `limit`

        defaults to 100, max 10000.


        **⚠ Date range cap (empirical, undocumented)**: Toss returns

        `400 Bad Request` when (`endDate` − `startDate`) exceeds ~7

        days, even though the public reference does not state a limit.

        For "last month"-style queries, call this op once per 7-day

        window and merge results client-side. Each call may take up

        to 60 seconds for high-volume merchants — the gateway does

        not impose a shorter timeout.


        Source: https://docs.tosspayments.com/reference#거래-조회'
      operationId: toss_list_transactions
      parameters:
      - name: connection_id
        in: query
        required: true
        schema:
          type: string
          description: mcpweave connection_id
          title: Connection Id
        description: mcpweave connection_id
      - name: startDate
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Startdate
      - name: endDate
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Enddate
      - name: startingAfter
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Startingafter
      - name: limit
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Limit
      - name: X-API-Key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Api-Key
      - name: mcpweave_session
        in: cookie
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Mcpweave Session
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        default:
          description: Native cafe24 response (200) or gateway error envelope (4xx/5xx)
  /api/v1/toss/v1/settlements:
    get:
      tags:
      - toss-rest
      summary: List settlement records by date range
      description: 'Returns settlement entries — each one represents a payout from

        Toss to the merchant''s bank account, with the Toss fee + VAT

        already broken out. Use this for monthly accounting close, or

        to reconcile against bank statements.


        `dateType=soldDate` filters by the date the underlying payment

        was approved; `dateType=paidOutDate` filters by the date Toss

        actually paid the merchant. Default is soldDate.


        **Sandbox returns empty** — Toss only emits settlement records

        in production. Test merchants always see an empty array

        regardless of date range. For sandbox dogfood, verify the call

        succeeds (200 OK with `[]`) but expect no rows.


        **Date range**: no documented hard limit. Settlement volume

        scales with daily transactions; expect `60s` timeouts on

        wide ranges for high-volume merchants. Pagination via

        `page` + `size` — `size` capped at 5000 per the reference.


        Source: https://docs.tosspayments.com/reference#정산-조회'
      operationId: toss_list_settlements
      parameters:
      - name: connection_id
        in: query
        required: true
        schema:
          type: string
          description: mcpweave connection_id
          title: Connection Id
        description: mcpweave connection_id
      - name: startDate
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Startdate
      - name: endDate
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Enddate
      - name: dateType
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Datetype
      - name: page
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Page
      - name: size
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Size
      - name: X-API-Key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Api-Key
      - name: mcpweave_session
        in: cookie
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Mcpweave Session
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        default:
          description: Native cafe24 response (200) or gateway error envelope (4xx/5xx)
  /api/v1/toss/v1/cash-receipts:
    post:
      tags:
      - toss-rest
      summary: Issue a cash receipt for a non-card payment
      description: 'Issues 현금영수증 to the National Tax Service (국세청) on behalf

        of the merchant. `customerIdentityNumber` is the buyer''s phone

        number (소득공제) or business registration number (지출증빙).


        For card / 간편결제 payments Toss issues the receipt

        automatically as part of confirm — call this endpoint only for

        cash, bank-transfer, virtual-account, or non-Toss payment

        methods you''re managing yourself.


        Source: https://docs.tosspayments.com/reference#현금영수증-발급-요청'
      operationId: toss_issue_cash_receipt
      parameters:
      - name: connection_id
        in: query
        required: true
        schema:
          type: string
          description: mcpweave connection_id
          title: Connection Id
        description: mcpweave connection_id
      - name: confirmation_token
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: 'ADR-030: required for irreversible op. First call returns token.'
          title: Confirmation Token
        description: 'ADR-030: required for irreversible op. First call returns token.'
      - name: X-API-Key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Api-Key
      - name: mcpweave_session
        in: cookie
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Mcpweave Session
      requestBody:
        content:
          application/json:
            schema:
              anyOf:
              - type: object
                additionalProperties: true
              - type: 'null'
              title: Body
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        default:
          description: Native cafe24 response (200) or gateway error envelope (4xx/5xx)
    get:
      tags:
      - toss-rest
      summary: List cash receipts issued on a given date
      description: 'Pagination via `cursor` — supply the next-page cursor returned

        in the previous response. Useful for monthly tax reporting

        (cross-checking against your accounting system).


        Source: https://docs.tosspayments.com/reference#현금영수증-조회'
      operationId: toss_list_cash_receipts
      parameters:
      - name: connection_id
        in: query
        required: true
        schema:
          type: string
          description: mcpweave connection_id
          title: Connection Id
        description: mcpweave connection_id
      - name: requestDate
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Requestdate
      - name: cursor
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Cursor
      - name: limit
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Limit
      - name: X-API-Key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Api-Key
      - name: mcpweave_session
        in: cookie
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Mcpweave Session
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        default:
          description: Native cafe24 response (200) or gateway error envelope (4xx/5xx)
  /api/v1/toss/v1/cash-receipts/{receiptKey}/cancel:
    post:
      tags:
      - toss-rest
      summary: Cancel a previously-issued cash receipt
      description: 'Voids a cash receipt at the National Tax Service. Cancellation

        happens same-day; for partial cancellation supply the `amount`

        to be voided.


        Source: https://docs.tosspayments.com/reference#현금영수증-발급-취소-요청'
      operationId: toss_cancel_cash_receipt
      parameters:
      - name: receiptKey
        in: path
        required: true
        schema:
          type: string
          title: Receiptkey
      - name: connection_id
        in: query
        required: true
        schema:
          type: string
          description: mcpweave connection_id
          title: Connection Id
        description: mcpweave connection_id
      - name: confirmation_token
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: 'ADR-030: required for irreversible op. First call returns token.'
          title: Confirmation Token
        description: 'ADR-030: required for irreversible op. First call returns token.'
      - name: X-API-Key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Api-Key
      - name: mcpweave_session
        in: cookie
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Mcpweave Session
      requestBody:
        content:
          application/json:
            schema:
              anyOf:
              - type: object
                additionalProperties: true
              - type: 'null'
              title: Body
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        default:
          description: Native cafe24 response (200) or gateway error envelope (4xx/5xx)