Toss Payments Cash Receipts API

openapi: 3.2.0
info:
  title: Toss Payments Core 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.
  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:
    BadRequest:
      description: The request was invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Missing or invalid secret key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    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).
    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
    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
  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_`.