openapi: 3.0.3
info:
  title: Toss Payments Core Billing Cash Receipts API
  description: 'The Toss Payments Core API is a REST interface for accepting and managing online payments in South Korea across cards, easy-pay wallets (Toss Pay, KakaoPay, Naver Pay), virtual accounts, bank transfer, and mobile-phone billing. This document models a representative, grounded subset of the Core API: payment confirmation and cancellation, recurring billing keys, virtual account issuance, cash receipts, transaction and settlement queries, and marketplace payouts. All requests authenticate with HTTP Basic auth - the secret API key is used as the username with an empty password, Base64 encoded (`Authorization: Basic base64(secretKey:)`). Asynchronous results (virtual account deposits, foreign payment cancellations, Brandpay and payout status changes) are delivered by webhooks, which are out of scope for this REST document. Field names follow the Korean documentation, translated where helpful. This is a modeled subset authored by API Evangelist from the public documentation, not an official Toss Payments OpenAPI artifact.'
  version: '2022-11-16'
  contact:
    name: Toss Payments Developer Center
    url: https://docs.tosspayments.com/en
  termsOfService: https://www.tosspayments.com
servers:
- url: https://api.tosspayments.com
  description: Toss Payments Core API (test and live selected by secret key prefix)
security:
- basicAuth: []
tags:
- name: Cash Receipts
  description: Korean cash receipt (현금영수증) issuance and cancellation.
paths:
  /v1/cash-receipts:
    post:
      operationId: issueCashReceipt
      tags:
      - Cash Receipts
      summary: Issue a cash receipt
      description: Issues a Korean cash receipt for income deduction or expense evidence.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CashReceiptRequest'
      responses:
        '200':
          description: The issued CashReceipt object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CashReceipt'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
    get:
      operationId: listCashReceipts
      tags:
      - Cash Receipts
      summary: Query cash receipts
      description: Queries issued cash receipts by request date with cursor pagination.
      parameters:
      - name: requestDate
        in: query
        required: true
        description: The date (YYYY-MM-DD) cash receipts were requested.
        schema:
          type: string
          format: date
      - name: limit
        in: query
        required: false
        description: Maximum number of records to return (up to 10000).
        schema:
          type: integer
          default: 100
      - name: startingAfter
        in: query
        required: false
        description: Cursor - return records after this receiptKey.
        schema:
          type: string
      responses:
        '200':
          description: A list of CashReceipt objects.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CashReceipt'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/cash-receipts/{receiptKey}/cancel:
    parameters:
    - name: receiptKey
      in: path
      required: true
      description: The key identifying the cash receipt.
      schema:
        type: string
    post:
      operationId: cancelCashReceipt
      tags:
      - Cash Receipts
      summary: Cancel a cash receipt
      description: Cancels a cash receipt in full or in part.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - amount
              properties:
                amount:
                  type: integer
                  description: The amount to cancel.
      responses:
        '200':
          description: The updated CashReceipt object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CashReceipt'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  responses:
    Unauthorized:
      description: Missing or invalid secret key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: The request was invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    CashReceiptRequest:
      type: object
      required:
      - amount
      - orderId
      - orderName
      - customerIdentityNumber
      - type
      properties:
        amount:
          type: integer
        orderId:
          type: string
        orderName:
          type: string
        customerIdentityNumber:
          type: string
          description: Phone number, card number, or business/national ID.
        type:
          type: string
          enum:
          - 소득공제
          - 지출증빙
        taxFreeAmount:
          type: integer
    CashReceipt:
      type: object
      properties:
        receiptKey:
          type: string
        orderId:
          type: string
        type:
          type: string
        issueNumber:
          type: string
        receiptUrl:
          type: string
        amount:
          type: integer
        taxFreeAmount:
          type: integer
        issueStatus:
          type: string
          enum:
          - IN_PROGRESS
          - COMPLETED
          - FAILED
    Error:
      type: object
      description: Standard Toss Payments error body.
      properties:
        code:
          type: string
          description: Machine-readable error code (for example INVALID_CARD_EXPIRATION).
        message:
          type: string
          description: Human-readable error message (Korean by default).
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: HTTP Basic authentication. Use your Toss Payments secret key as the username and leave the password empty, then Base64 encode `secretKey:` for the Authorization header. Test keys are prefixed `test_sk_` / `test_gsk_` and live keys `live_sk_` / `live_gsk_`.