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