KOMOJU Payment Methods API

openapi: 3.0.3
info:
  title: KOMOJU API
  description: >-
    KOMOJU is a Japan-focused global payment gateway operated by Degica. The REST
    API accepts payments across Japanese and international payment methods -
    credit cards, convenience store (konbini), bank transfer, Pay-easy (ATM),
    and e-money / mobile wallets such as PayPay, Merpay, au PAY, Rakuten Pay,
    LINE Pay, Alipay, and WeChat Pay - plus a hosted checkout (Sessions),
    tokenization, saved customers, subscriptions, and webhook events.


    Base URL: https://komoju.com/api/v1. Authentication is HTTP Basic: send your
    secret (or publishable, where allowed) API key as the username and leave the
    password empty (for example `curl -u secret_key: ...`). Separate live and
    test key pairs are issued per merchant account. POST requests support
    idempotency via the `X-KOMOJU-IDEMPOTENCY` header, and an optional
    `X-KOMOJU-API-VERSION` header pins the API version.


    This description is grounded in the public KOMOJU API reference
    (doc.komoju.com). Paths, methods, and authentication are confirmed against
    that reference. Request/response schemas below are a representative, partly
    modeled subset - some object properties are simplified or marked
    additionalProperties where the full field list is extensive; consult the
    official reference for exhaustive field-level detail.
  version: '1.0'
  contact:
    name: KOMOJU (Degica)
    url: https://en.komoju.com
  license:
    name: Proprietary
    url: https://en.komoju.com/terms/
servers:
  - url: https://komoju.com/api/v1
    description: KOMOJU API (live and test share this host; the key pair selects the environment)
security:
  - basicAuth: []
tags:
  - name: Payments
    description: Create, capture, refund, cancel, and query payments across all payment methods.
  - name: Sessions
    description: Hosted checkout sessions that collect payment or customer details.
  - name: Tokens
    description: Tokenize payment details (short-term tokens and 3DS secure tokens).
  - name: Customers
    description: Store and manage customers with saved payment details for reuse.
  - name: Subscriptions
    description: Recurring payments charged against a saved customer.
  - name: Payment Methods
    description: List the payment methods available to the authenticated merchant.
  - name: Events
    description: Webhook events emitted by KOMOJU, queryable after the fact.
  - name: Barcodes
    description: Konbini payment barcodes for compatible convenience-store payments.
paths:
  /payments:
    get:
      operationId: listPayments
      tags: [Payments]
      summary: List payments
      description: >-
        Retrieves a paginated list of payments. Supports pagination via `page`
        and `per_page`, filtering by `currency`, `external_order_num`, and
        `status`, and a time range via `start_time` and `end_time`.
      parameters:
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/PerPage'
        - name: status
          in: query
          required: false
          schema:
            type: string
            enum: [pending, authorized, captured, refunded, cancelled, expired, failed]
        - name: currency
          in: query
          required: false
          schema:
            type: string
            example: JPY
      responses:
        '200':
          description: A paginated list of payments.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentList'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createPayment
      tags: [Payments]
      summary: Create a payment
      description: >-
        Creates a payment for a given `amount` and `currency`. Provide either
        `payment_details` (a payment method type plus its attributes, or a token
        string) for a one-time payment, or a `customer` ID to charge a saved
        payment method - but not both. Set `capture` to false to authorize now
        and capture later (two-step capture).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentCreateInput'
      responses:
        '200':
          description: The created payment.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Payment'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
  /payments/{id}:
    parameters:
      - $ref: '#/components/parameters/PaymentId'
    get:
      operationId: showPayment
      tags: [Payments]
      summary: Show a payment
      description: Retrieves a single payment object by its `id`.
      responses:
        '200':
          description: The requested payment.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Payment'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      operationId: updatePayment
      tags: [Payments]
      summary: Update a payment
      description: Updates a payment. Only `description` and `metadata` can be changed.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                description:
                  type: string
                metadata:
                  type: object
                  additionalProperties: true
      responses:
        '200':
          description: The updated payment.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Payment'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /payments/{id}/capture:
    parameters:
      - $ref: '#/components/parameters/PaymentId'
    post:
      operationId: capturePayment
      tags: [Payments]
      summary: Capture a payment
      description: >-
        Captures a previously authorized payment. Only works when the payment
        was created with `capture` set to false, or via a session with `capture`
        set to `manual`.
      responses:
        '200':
          description: The captured payment.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Payment'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /payments/{id}/refund:
    parameters:
      - $ref: '#/components/parameters/PaymentId'
    post:
      operationId: refundPayment
      tags: [Payments]
      summary: Refund a payment
      description: >-
        Refunds an amount from an existing payment. If no `amount` is specified,
        the whole payment is refunded.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                amount:
                  type: integer
                  description: Amount to refund in the smallest currency unit. Omit to refund in full.
                description:
                  type: string
      responses:
        '200':
          description: The refunded payment.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Payment'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /payments/{id}/cancel:
    parameters:
      - $ref: '#/components/parameters/PaymentId'
    post:
      operationId: cancelPayment
      tags: [Payments]
      summary: Cancel a payment
      description: >-
        Cancels a payment. The payment must be in a `pending` or `authorized`
        state in order to be cancelled.
      responses:
        '200':
          description: The cancelled payment.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Payment'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /payments/{id}/refund_request:
    parameters:
      - $ref: '#/components/parameters/PaymentId'
    post:
      operationId: createRefundRequest
      tags: [Payments]
      summary: Create a refund request
      description: >-
        Requests that a payment be refunded manually. Used for payment methods
        that do not support automatic refunds, such as konbini. A destination
        bank account must be specified. The refund is processed manually at a
        later date and may be rejected.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                amount:
                  type: integer
                bank_account:
                  type: object
                  description: Destination bank account for the manual refund.
                  additionalProperties: true
      responses:
        '200':
          description: The refund request result.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /sessions:
    post:
      operationId: createSession
      tags: [Sessions]
      summary: Create a session
      description: >-
        Creates a hosted checkout session. Three modes are supported: `payment`
        (default; creates a payment when the user completes the session),
        `customer` (creates or updates a customer for delayed billing or
        subscriptions), and `customer_payment` (charges upfront and saves the
        customer's payment details in one flow).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SessionCreateInput'
      responses:
        '200':
          description: The created session, including a hosted `session_url`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Session'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
  /sessions/{id}:
    parameters:
      - $ref: '#/components/parameters/SessionId'
    get:
      operationId: showSession
      tags: [Sessions]
      summary: Show a session
      description: >-
        Retrieves a session by its ID. A session's status changes when the user
        completes or cancels payment; poll this endpoint or listen via webhooks.
      responses:
        '200':
          description: The requested session.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Session'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /sessions/{id}/cancel:
    parameters:
      - $ref: '#/components/parameters/SessionId'
    post:
      operationId: cancelSession
      tags: [Sessions]
      summary: Cancel a session
      description: Cancels a session.
      responses:
        '200':
          description: The cancelled session.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Session'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /sessions/{id}/pay:
    parameters:
      - $ref: '#/components/parameters/SessionId'
    post:
      operationId: paySession
      tags: [Sessions]
      summary: Pay for a session
      description: >-
        Provides customer payment details to pay for a session directly. This
        endpoint may be called with a publishable key.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                payment_details:
                  $ref: '#/components/schemas/PaymentDetails'
      responses:
        '200':
          description: The session after the pay attempt.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Session'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /tokens:
    post:
      operationId: createToken
      tags: [Tokens]
      summary: Create a token
      description: >-
        Creates a token from the given `payment_details`. Best made directly
        from a client application so sensitive card data never touches your
        server. The resulting token string can be used as `payment_details` in a
        later payment. May be called with a publishable key.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                payment_details:
                  $ref: '#/components/schemas/PaymentDetails'
                currency:
                  type: string
                  description: Optional currency the token is locked to.
      responses:
        '200':
          description: The created token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Token'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
  /secure_tokens:
    post:
      operationId: createSecureToken
      tags: [Tokens]
      summary: Create a secure token (3DS)
      description: >-
        Creates a SecureToken from credit card `payment_details` or a `customer`
        ID. The response includes an authentication URL for 3D Secure. Once
        authenticated, the secure token ID can be used as `payment_details` in a
        later payment.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                payment_details:
                  $ref: '#/components/schemas/PaymentDetails'
                customer:
                  type: string
                return_url:
                  type: string
                  format: uri
      responses:
        '200':
          description: The created secure token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SecureToken'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
  /secure_tokens/{id}:
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
    get:
      operationId: showSecureToken
      tags: [Tokens]
      summary: Show a secure token
      description: Retrieves a single SecureToken object by its `id`.
      responses:
        '200':
          description: The requested secure token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SecureToken'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /customers:
    get:
      operationId: listCustomers
      tags: [Customers]
      summary: List customers
      description: Retrieves a paginated list of previously-registered customers.
      parameters:
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/PerPage'
      responses:
        '200':
          description: A paginated list of customers.
          content:
            application/json:
              schema:
                type: object
                properties:
                  total:
                    type: integer
                  page:
                    type: integer
                  per_page:
                    type: integer
                  resources:
                    type: array
                    items:
                      $ref: '#/components/schemas/Customer'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createCustomer
      tags: [Customers]
      summary: Create a customer
      description: >-
        Creates a customer with the specified `payment_details`, stored in a
        PCI-DSS-compliant way. The customer `id` can then be supplied instead of
        `payment_details` when creating a payment.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomerInput'
      responses:
        '200':
          description: The created customer.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Customer'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
  /customers/{id}:
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
    get:
      operationId: showCustomer
      tags: [Customers]
      summary: Show a customer
      description: Retrieves customer personal information.
      responses:
        '200':
          description: The requested customer.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Customer'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      operationId: updateCustomer
      tags: [Customers]
      summary: Update a customer
      description: Updates the customer with the given `id`. A new set of `payment_details` may be specified.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomerInput'
      responses:
        '200':
          description: The updated customer.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Customer'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: deleteCustomer
      tags: [Customers]
      summary: Delete a customer
      description: Deletes the customer with the given `id`, erasing the stored payment details.
      responses:
        '200':
          description: The deleted customer.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Customer'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /subscriptions:
    get:
      operationId: listSubscriptions
      tags: [Subscriptions]
      summary: List subscriptions
      description: Lists existing subscriptions.
      parameters:
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/PerPage'
      responses:
        '200':
          description: A list of subscriptions.
          content:
            application/json:
              schema:
                type: object
                properties:
                  resources:
                    type: array
                    items:
                      $ref: '#/components/schemas/Subscription'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createSubscription
      tags: [Subscriptions]
      summary: Create a subscription
      description: >-
        Creates a subscription (recurring payment) against a saved `customer`.
        The `period` may be `weekly`, `monthly`, or `yearly`. Subscriptions are
        immutable once created - delete and recreate to change one.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubscriptionInput'
      responses:
        '200':
          description: The created subscription.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Subscription'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
  /subscriptions/{id}:
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
    get:
      operationId: showSubscription
      tags: [Subscriptions]
      summary: Show a subscription
      description: Shows an existing subscription, including its customer and scrubbed payment details.
      responses:
        '200':
          description: The requested subscription.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Subscription'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: deleteSubscription
      tags: [Subscriptions]
      summary: Delete a subscription
      description: Deletes a subscription. Its recurring payments stop once deleted.
      responses:
        '200':
          description: The deleted subscription.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Subscription'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /payment_methods:
    get:
      operationId: listPaymentMethods
      tags: [Payment Methods]
      summary: List payment methods
      description: >-
        Lists the payment methods available to the authenticated merchant
        (for example credit_card, konbini, bank_transfer, pay_easy, paypay,
        merpay, au_pay, rakutenpay, linepay, alipay, wechatpay, paidy).
      parameters:
        - name: amount
          in: query
          required: false
          schema:
            type: integer
        - name: currency
          in: query
          required: false
          schema:
            type: string
            example: JPY
      responses:
        '200':
          description: A list of available payment methods.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PaymentMethod'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /events:
    get:
      operationId: listEvents
      tags: [Events]
      summary: List events
      description: Lists past webhook events from most-recent to least-recent.
      parameters:
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/PerPage'
      responses:
        '200':
          description: A paginated list of events.
          content:
            application/json:
              schema:
                type: object
                properties:
                  resources:
                    type: array
                    items:
                      $ref: '#/components/schemas/Event'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /events/{id}:
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
    get:
      operationId: showEvent
      tags: [Events]
      summary: Show an event
      description: Retrieves an event by its `id`. Event IDs come from webhooks or the events list.
      responses:
        '200':
          description: The requested event.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Event'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /barcodes/{payment_id}:
    parameters:
      - name: payment_id
        in: path
        required: true
        schema:
          type: string
    get:
      operationId: showBarcode
      tags: [Barcodes]
      summary: Show a konbini barcode
      description: >-
        Fetches the latest barcode for a compatible konbini payment. If the
        barcode is still generating, the response has `status` of `pending` and
        a `retry_after` value (seconds) to wait before retrying.
      responses:
        '200':
          description: The barcode, or a pending status.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum: [ready, pending]
                  retry_after:
                    type: integer
                  barcode:
                    type: string
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: >-
        HTTP Basic Authentication. Use your KOMOJU API key as the username and
        leave the password empty (for example `curl -u secret_key: ...`). Secret
        keys grant full access; publishable keys are limited to creating tokens
        and paying for sessions. Separate live and test key pairs exist per
        merchant.
  parameters:
    Page:
      name: page
      in: query
      required: false
      schema:
        type: integer
        default: 1
    PerPage:
      name: per_page
      in: query
      required: false
      schema:
        type: integer
        default: 25
    PaymentId:
      name: id
      in: path
      required: true
      description: The payment ID.
      schema:
        type: string
    SessionId:
      name: id
      in: path
      required: true
      description: The session ID.
      schema:
        type: string
  responses:
    Unauthorized:
      description: Invalid authorization (missing or invalid API key).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    UnprocessableEntity:
      description: The request payload failed validation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
            message:
              type: string
            param:
              type: string
    PaymentDetails:
      description: >-
        Payment method details. Either an object whose `type` selects the
        method (credit_card, konbini, bank_transfer, pay_easy, paypay, merpay,
        au_pay, rakutenpay, linepay, alipay, wechatpay, paidy, ...) plus the
        attributes for that method, or a token string from Create Token /
        Create Secure Token.
      oneOf:
        - type: string
          description: A token or secure token ID.
        - type: object
          properties:
            type:
              type: string
              enum:
                - credit_card
                - konbini
                - bank_transfer
                - pay_easy
                - paypay
                - merpay
                - au_pay
                - rakutenpay
                - linepay
                - alipay
                - wechatpay
                - paidy
          additionalProperties: true
    PaymentCreateInput:
      type: object
      required:
        - amount
        - currency
      properties:
        amount:
          type: integer
          description: Amount in the smallest currency unit (for JPY, this is yen).
          example: 1000
        currency:
          type: string
          example: JPY
        payment_details:
          $ref: '#/components/schemas/PaymentDetails'
        customer:
          type: string
          description: A saved customer ID. Mutually exclusive with payment_details.
        capture:
          type: boolean
          description: Set to false to authorize now and capture later.
          default: true
        external_order_num:
          type: string
        description:
          type: string
        metadata:
          type: object
          additionalProperties: true
    Payment:
      type: object
      properties:
        id:
          type: string
        resource:
          type: string
          example: payment
        status:
          type: string
          enum: [pending, authorized, captured, refunded, cancelled, expired, failed]
        amount:
          type: integer
        currency:
          type: string
        payment_deadline:
          type: string
          format: date-time
        payment_details:
          type: object
          additionalProperties: true
        payment_method_fee:
          type: integer
        total:
          type: integer
        customer:
          type: string
          nullable: true
        refunds:
          type: array
          items:
            type: object
            additionalProperties: true
        refunded_at:
          type: string
          format: date-time
          nullable: true
        external_order_num:
          type: string
          nullable: true
        metadata:
          type: object
          additionalProperties: true
        created_at:
          type: string
          format: date-time
    PaymentList:
      type: object
      properties:
        total:
          type: integer
        page:
          type: integer
        per_page:
          type: integer
        resources:
          type: array
          items:
            $ref: '#/components/schemas/Payment'
    SessionCreateInput:
      type: object
      required:
        - amount
        - currency
      properties:
        amount:
          type: integer
        currency:
          type: string
          example: JPY
        mode:
          type: string
          enum: [payment, customer, customer_payment]
          default: payment
        capture:
          type: string
          enum: [auto, manual]
        return_url:
          type: string
          format: uri
        default_locale:
          type: string
          example: ja
        payment_types:
          type: array
          description: Restrict the session to specific payment method types.
          items:
            type: string
        customer:
          type: string
        external_order_num:
          type: string
        metadata:
          type: object
          additionalProperties: true
    Session:
      type: object
      properties:
        id:
          type: string
        resource:
          type: string
          example: session
        mode:
          type: string
          enum: [payment, customer, customer_payment]
        status:
          type: string
          enum: [pending, completed, cancelled, expired]
        amount:
          type: integer
        currency:
          type: string
        session_url:
          type: string
          format: uri
          description: The hosted checkout URL to redirect the customer to.
        return_url:
          type: string
          format: uri
        payment:
          type: object
          nullable: true
          additionalProperties: true
        customer:
          type: string
          nullable: true
        created_at:
          type: string
          format: date-time
        expires_at:
          type: string
          format: date-time
    Token:
      type: object
      properties:
        id:
        

# --- truncated at 32 KB (35 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/komoju/refs/heads/main/openapi/komoju-openapi.yml