Starting transactions from other apps

KOMOJU Terminal allows signed, pre-vetted applications to be installed by us on the terminal. This would allow merchants or system integrators to run their own apps on our terminal, and invoke the payment process from this application.

Starting the payment process from a third-party application

The terminal application exposes an endpoint which can be called from any other application that is installed on the device. These endpoints start with komoju:// and can be launched using the Intent function from other Android apps.

An example of this would be:

komoju://terminal/start/eyJhY3Rpb24iOiJzYWxlIiwiYW1vdW50IjoxMDAwLCJjYW5jZWxfdXJsIjoidGVzdDovL2NhbmNlbCIsInJldHVybl91cmwiOiJ0ZXN0Oi8vcmV0dXJuIn0=

The URL contains a Base64 encoded JSON payload which contains all the necessary details to initiate a payment through the app.

An example of this payload is:

{
   "action":"sale",
   "amount":1000,
   "external_order_number":"1234567890",
   "cancel_url":"test://cancel",
   "return_url":"test://return"
}

The parameters that can be supplied are:

Parameter Name	Required	Description
action	Yes	This is equal to either `sale` or `pre_auth`, depending on the intended action of the invoker.
amount	Yes	This is an integer value of the amount in Japanese Yen (JPY).
external_order_number	No	An order ID which is generated by your system. This is not mandatory. If left blank, the terminal will generate a number randomly. This number needs to be unique for every transaction.
cancel_url	Yes	The cancel URL when the transaction is cancelled. This is usually mapped to the Activity which displays the cancellation / error message on your application. Do not add a trailing slash on the URL.
return_url	Yes	The return URL when the transaction is successful. This is usually mapped to the "Thank You" or "Success" screen of your application. Do not add a trailing slash on the URL.

Returning payment status

The terminal application will redirect back to the cancel_url in case of cancellation, or return back to the return_url in case of success. The URLs provided in these parameters must be defined through an intent-filter in your destination application.

For example, if your destination application's payment success screen is mapped to yourapp://payment/success, you can provide this URL to the return_url parameter when starting the payment.

The payment application will redirect the user to the URL yourapp://payment/success/:payment_id , with the payment ID appended to the URL. This payment ID can be used to call our API to fetch the status of the payment.

Sample Application

We provide a sample application for your reference during implementation. Please contact us for more information to obtain the sample application source.