@komoju/komoju-sdk

v1.0.0

Published

18 days ago

OpenAPI client for @komoju/komoju-sdk

0High
0Medium
0Low

komoju-publish

chathura.pathiranage

axios typescript openapi-client openapi-generator @komoju/komoju-sdk

@komoju/komoju-sdk @1.0.0

The KOMOJU Node SDK is a full-featured TypeScript/JavaScript client for the KOMOJU Payments API. It works with any Node.js application or framework.

For a full reference of all available endpoints and models, see the KOMOJU API Reference.

Installation

npm install @komoju/[email protected]

Getting Started

Get your API keys from the KOMOJU Merchant Settings and configure the client.

import { Configuration, SessionsApi } from '@komoju/komoju-sdk';

const config = new Configuration();
config.setApiKey('YOUR_SECRET_KEY');

Example: Hosted Page Payment

The following example walks through a basic hosted page payment flow. For a full guide, see the Hosted Page Integration Guide.

1. Creating a Session

When your customer is ready to pay, create a session and redirect them to the returned sessionUrl.

const sessionsApi = new SessionsApi(config);

const session = await sessionsApi.createSession({
  createSessionRequest: {
    amount: 1000,
    currency: 'JPY',
    returnUrl: 'https://your-site.com/orders/return',
  },
});

res.redirect(session.data.sessionUrl);

2. Handling the Return URL

After the customer pays, KOMOJU redirects them back to your returnUrl with a session_id query param appended:

https://your-site.com/orders/return?session_id=xxxxx

Fetch the session to check the outcome:

const { session_id } = req.query;

const result = await sessionsApi.showSession({ id: session_id });
const komojuSession = result.data;

if (komojuSession.status === SessionStatus.Completed) {
  // payment.status will be "captured", "authorized", or "pending"
  console.log(`Payment ${komojuSession.payment.status}`);
} else {
  console.log('Payment was cancelled or failed');
}

3. Set Up Webhooks (Recommended)

It is possible that the redirect in step 2 fails, possibly due to the user closing their browser, network issues, etc. Or, that the capture will only take place later on, such as with Convenience Store payments. To account for this, we recommend setting up a Webhook to listen for payment events such as payment.captured, payment.authorized, and payment.cancelled. Configure your webhook URL in the KOMOJU Merchant Dashboard.

Verifying Webhook Signatures

To ensure a webhook request genuinely came from KOMOJU, set a secret token when creating or updating the webhook. KOMOJU then signs every delivery with a SHA-256 HMAC of the raw request body in the X-Komoju-Signature header, which you can recompute and verify.

See Webhooks → Secret Token for the full explanation and code examples.

API Endpoints

All URIs are relative to https://komoju.com/api/v1

| Class | Method | HTTP request | Description | |------------ | ------------- | ------------- | -------------| | BarcodesApi | showBarcode | GET /barcodes/{payment_id} | Barcode: Show | | ChargebacksApi | acceptChargebackRequest | POST /chargeback_requests/{id}/accept | Chargeback: Accept | | ChargebacksApi | defendChargebackRequest | POST /chargeback_requests/{id}/defend | Chargeback: Defend | | ChargebacksApi | listChargebackRequests | GET /chargeback_requests | Chargeback: List | | ChargebacksApi | showChargebackRequest | GET /chargeback_requests/{id} | Chargeback: Show | | DisbursementsApi | cancelDisbursement | POST /disbursements/{id}/cancel | Disbursement: Cancel | | DisbursementsApi | createDisbursement | POST /disbursements | Disbursement: Create | | DisbursementsApi | disbursementReport | GET /disbursements/report | Disbursement: Report | | DisbursementsApi | listDisbursements | GET /disbursements | Disbursement: List | | DisbursementsApi | showDisbursement | GET /disbursements/{id} | Disbursement: Show | | EventsApi | listEvents | GET /events | Event: List | | EventsApi | showEvent | GET /events/{id} | Event Show | | OneClickApi | deleteExternalCustomer | DELETE /external_customers/{id} | External Customer: Destroy | | PaymentsApi | cancelPayment | POST /payments/{id}/cancel | Payment: Cancel | | PaymentsApi | capturePayment | POST /payments/{id}/capture | Payment: Capture | | PaymentsApi | createPayment | POST /payments | Payment: Create | | PaymentsApi | createRefundRequest | POST /payments/{id}/refund_request | Payment: Refund Request | | PaymentsApi | finalizePayment | POST /payments/{id}/finalize | Payment: Finalize | | PaymentsApi | listPaymentMethods | GET /payment_methods | Payment Method: List | | PaymentsApi | listPayments | GET /payments | Payment: List | | PaymentsApi | refundPayment | POST /payments/{id}/refund | Payment: Refund | | PaymentsApi | showPayment | GET /payments/{id} | Payment: Show | | PaymentsApi | updatePayment | PATCH /payments/{id} | Payment: Update | | PlatformModelApi | balanceTransfer | POST /balances/{currency}/transfer | Balance: Transfer | | PlatformModelApi | createFile | POST /merchants/{merchant_id}/files | File: Create | | PlatformModelApi | createMerchant | POST /merchants | Merchant: Create | | PlatformModelApi | createMerchantBalanceTransfer | POST /merchants/{merchant_id}/balances/{currency}/transfer | Balance: Transfer | | PlatformModelApi | editMerchantBalanceSettings | PUT /merchants/{merchant_id}/balances/{currency}/settings | Balances: Edit Settings | | PlatformModelApi | listLiveApplicationPaymentMethods | GET /live_application/{merchant_id}/payment_methods | Live Application: Payment Methods | | PlatformModelApi | listMerchants | GET /merchants | Merchant: List | | PlatformModelApi | listSubmerchantPayments | GET /merchants/{merchant_id}/payments | Payment: List for Merchant | | PlatformModelApi | listSubmerchantSettlements | GET /merchants/{merchant_id}/settlements | Settlement: List | | PlatformModelApi | merchantBalanceTransactions | GET /merchants/{merchant_id}/balances/{currency}/transactions | Balance: Transactions | | PlatformModelApi | showFile | GET /merchants/{merchant_id}/files/{id} | File: Show | | PlatformModelApi | showLiveApplication | GET /live_application/{merchant_id} | Live Application: Show | | PlatformModelApi | showLiveApplicationPaymentMethod | GET /live_application/{merchant_id}/payment_methods/{payment_method} | Live Application: Show Payment Method | | PlatformModelApi | showMerchant | GET /merchants/{id} | Merchant: Show | | PlatformModelApi | showMerchantBalance | GET /merchants/{merchant_id}/balances/{currency} | Balance: Show | | PlatformModelApi | showMerchantBalanceSettings | GET /merchants/{merchant_id}/balances/{currency}/settings | Balance: Show Settings | | PlatformModelApi | showMerchantBalanceTransaction | GET /merchants/{merchant_id}/balances/{currency}/transactions/{transaction_uuid} | Balance: Transaction | | PlatformModelApi | showSubmerchantSettlement | GET /merchants/{merchant_id}/settlements/{id} | Settlement: Show | | PlatformModelApi | simulateLiveApplicationPaymentMethodStatus | PATCH /live_application/{merchant_id}/payment_methods/{payment_method}/simulate_status | Live Application: Simulate Payment Method Status | | PlatformModelApi | simulateLiveApplicationStatus | PATCH /live_application/{merchant_id}/simulate_status | Live Application: Simulate Status | | PlatformModelApi | submerchantSettlementCSV | GET /merchants/{merchant_id}/settlements/{id}/csv | Settlement: CSV | | PlatformModelApi | submerchantSettlementPDF | GET /merchants/{merchant_id}/settlements/{id}/pdf | Settlement: PDF | | PlatformModelApi | submerchantSettlementXLS | GET /merchants/{merchant_id}/settlements/{id}/xls | Settlement: XLS | | PlatformModelApi | updateLiveApplication | PATCH /live_application/{merchant_id} | Live Application: Update | | PlatformModelApi | updateLiveApplicationPaymentMethod | PATCH /live_application/{merchant_id}/payment_methods/{payment_method} | Live Application: Update Payment Method | | PlatformModelApi | updateMerchant | PATCH /merchants/{id} | Merchant: Update | | SecureTokensApi | createSecureToken | POST /secure_tokens | SecureToken: Create | | SecureTokensApi | showSecureToken | GET /secure_tokens/{id} | SecureToken: Show | | SessionsApi | cancelSession | POST /sessions/{id}/cancel | Session: Cancel | | SessionsApi | createSession | POST /sessions | Session: Create | | SessionsApi | paySession | POST /sessions/{id}/pay | Session: Pay | | SessionsApi | showSession | GET /sessions/{id} | Session: Show | | SettlementsApi | balanceTransactions | GET /balances/{currency}/transactions | Balance: Transactions | | SettlementsApi | listSettlements | GET /settlements | Settlement: Index | | SettlementsApi | showBalance | GET /balances/{currency} | Balance: Show | | SettlementsApi | showSettlement | GET /settlements/{id} | Settlement: Show | | SettlementsApi | showSettlementCSV | GET /settlements/{id}/csv | Settlement: CSV | | SettlementsApi | showSettlementPDF | GET /settlements/{id}/pdf | Settlement: PDF | | SettlementsApi | showSettlementXLS | GET /settlements/{id}/xls | Settlement: XLS | | SettlementsApi | showTransaction | GET /balances/{currency}/transactions/{transaction_uuid} | Balance: Transaction | | SubscriptionsApi | createCustomer | POST /customers | Customer: Create | | SubscriptionsApi | createSubscription | POST /subscriptions | Subscription: Create | | SubscriptionsApi | deleteCustomer | DELETE /customers/{id} | Customer: Destroy | | SubscriptionsApi | deleteSubscription | DELETE /subscriptions/{id} | Subscription: Destroy | | SubscriptionsApi | listCustomers | GET /customers | Customer: List | | SubscriptionsApi | listSubscriptions | GET /subscriptions | Subscription: List | | SubscriptionsApi | showCustomer | GET /customers/{id} | Customer: Show | | SubscriptionsApi | showSubscription | GET /subscriptions/{id} | Subscription: Show | | SubscriptionsApi | updateCustomer | PATCH /customers/{id} | Customer: Update | | TokensApi | createToken | POST /tokens | Token: Create |

Models

Authorization

KOMOJU uses HTTP Basic Auth. Use config.setApiKey('your_key') to authenticate — this sets the API key as the HTTP Basic username with an empty password.

Building from Source

npm install
npm run build