The cloud terminal API allows you to interact directly with connected terminal devices through our KOMOJU API.

Cloud API integrations are the easiest and recommended way to get started with Terminal.

Cloud Push API

Available features

Push session to device
Print receipt from session
Cancel device session

Example flow of cloud API

The following example demonstrates how the Cloud Terminal API can be used to initiate a payment session on the device, and return payment status back to the POS system or application.

This is just an example of how a potential flow will look like. Depending on your system, industry and setup you may opt for a different flow. Our API should be able to accommodate the majority of payment flows without any drastic system logic changes.

The app initiates a session using our Sessions API and includes all available metadata as needed, such as amount, currency, customer information and line items.
The app receives a newly created session with associated session ID, and associates this session ID with the internal record of the transaction.
The app calls the Push Session method on the cloud API which initiates the payment process on the terminal .
The customer completes the payment process on the terminal.
The app listens for a inbound webhook, or polls the status of the session.
When the session is completed, the goods are delivered or the services are rendered.

API Reference

Initiating a payment on the device

Step 1: Create Session

Firstly, create a Session that contains all the payment information. You can include your external order number and other parameters to be associated with this payment. This information will also be fed back to you via the webhook mechanism.

POST https://komoju.com/api/v1/sessions

Example Request

{
  "default_locale": "ja",
  "payment_data": {
    "capture": "auto",
    "external_order_num": "12345678"
  },
  "mode": "payment",
  "amount": 1000,
  "currency": "JPY",
  "payment_types": [
    "credit_card_terminal"
  ]
}

Response

{
    "id": "6k4xs4rah6k8bt4ebnufqwhcb",
    "resource": "session",
    "mode": "payment",
    "amount": 1000,
    "currency": "JPY",
    "session_url": "https://komoju.com/sessions/6k4xs4rah6k8bt4ebnufqwhcb",
    "return_url": null,
    "default_locale": "ja",
    "payment_methods": [
        {
            "type": "credit_card_terminal",
            "amount": 1000,
            "currency": "JPY",
            "exchange_rate": 1.0,
            "hashed_gateway": "e6212ad60e88dbd0"
        }
    ],
    "created_at": "2023-12-12T11:55:46.000+09:00",
    "cancelled_at": null,
    "completed_at": null,
    "status": "pending",
    "expired": false,
    "metadata": {},
    "payment": null,
    "secure_token": null,
    "payment_data": {
        "external_order_num": "12345678",
        "capture": "auto"
    }
}

Step 2: Push session to terminal device

The session ID can be used to push this transaction session to the device. When pushed, the device will display the payments initiation step and will be ready to be used.

The terminal ID and the session ID will need to be provided.

This can be done using the following endpoint:

POST https://komoju.com/api/v1/terminals/{terminal_id}/sessions/{session_id}/push

Response

The response will be a 200 Success message. If not successful, it will return an error message.

{
  "status": "success"
}

{
  "error": {
    "code": "error",
    "message": "Session must be pending to be pushed to the device."
  }
}

Step 3: Complete Payment on Device

The device is now ready to receive the payment and complete it. Once completed, a webhook can be listened for, or the session status can be polled in order to determine whether the payment was successful, or not.

Step 4: Webhook

A webhook can be consumed to notify the initiator (eg. POS device) of a successful transaction. Sale transactions will always have captured as their final transaction status, while Auth-only transactions will have authorized as their final status.

The metadata section will contain information from the POS transaction, including AID, Application Label, Cardholder Name and Transaction Counters. This information can be used to produce custom receipts at the POS machine side, or for record keeping .

{
  "id": "4jo7t14vumnhu5cmretrugxiw",
  "type": "payment.updated",
  "resource": "event",
  "data": {
    "id": "28e3dhxc8gdr3zdnsdzea17qf",
    "resource": "payment",
    "status": "captured",
    "amount": 1000,
    "tax": 0,
    "customer": null,
    "payment_deadline": "2023-12-14T14:59:59Z",
    "payment_details": {
      "type": "credit_card_terminal",
      "email": null,
      "brand": "visa",
      "last_four_digits": "0010",
      "month": 11,
      "year": 2024
    },
    "payment_method_fee": 0,
    "total": 1000,
    "currency": "JPY",
    "description": null,
    "captured_at": "2023-12-12T03:07:29Z",
    "external_order_num": "91176632142",
    "metadata": {
      "action": "sale",
      "aid": "A0000000031010",
      "application_label": "VISA CREDIT",
      "arc": "00",
      "atc": "02D4",
      "cardholderName": "VISA CREDIT/CARDHOLDER",
      "cardholderVerification": "",
      "cryptogramType": "ARQC",
      "cryptogramValue": "12067CDEAEC09F26",
      "method": "CL",
      "origin": "terminal",
      "terminalSeqCounter": "00000002",
      "tsi": "0000",
      "tvr": "0000000000"
    },
    "created_at": "2023-12-12T03:07:28Z",
    "amount_refunded": 0,
    "locale": "ja",
    "session": "ebjljw181tdwpybolb3jpthv6",
    "customer_family_name": null,
    "customer_given_name": null,
    "mcc": null,
    "statement_descriptor": null,
    "refunds": [],
    "refund_requests": []
  },
  "created_at": "2023-12-12T03:07:30Z",
  "reason": null
}

Printing a receipt

If you would like to invoke the receipt printer to print a receipt from a previously completed session, you can do so by calling the following API endpoint.

Just as with the previous calls, it is required to provide a terminal ID and a session ID to invoke the printer.

POST https://komoju.com/api/v1/terminals/{terminal_id}/sessions/{session_id}/print

The response will be a 200 Success message. If not successful, it will return an error message.

{
  "status": "success"
}

{
  "error": {
    "code": "error",
    "message": "Could not print session on device."
  }
}

Cancelling a session

After the session has been pushed to the device, you have the option to fully abort the payment process by sending a cancel request. Once a session is cancelled it cannot be paid. This is useful in unattended cases where the system needs to forcibly prevent the user from proceeding with a transaction.

POST https://komoju.com/api/v1/terminals/{terminal_id}/sessions/{session_id}/cancel

The response will be a 200 Success message. If not successful, it will return an error message.

{
  "status": "success"
}

{
  "error": {
    "code": "error",
    "message": "Could not cancel session."
  }
}