Initiate a payment

🚧

Pre condition:

Generate merchant token, for more info click here.

Get connected devices

To get all active device, use the following end point:

View the partner API: Get terminals

To see the data fields associated to a terminal go to the terminal model page.

Note: make sure your Klearly app is in the right mode. Learn how

If your POS support it, you can let the merchant choose the terminal to which they would like to send the payment to. This means you will present a screen to the merchant, after closing a bill or a table, with the list of active terminals. Use the GET terminals call to show this list dynamically.

📘

Name a terminal

You, your reseller or your merchants can also change the name of a terminal to make it easier to recognize it while choosing to which terminal to set a payment for. This can be done in partner hub or merchant dashboard, in the hardware section.

This name will appear on the terminal screen and in all reports.

Initiate sale payment

To initiate a payment, use the device ID you received from the response of device list.

View the partner API: Initiate Payment

To see the data fields associated to a payment go to the payment model page.

📘

Meta data

It is recommended to send the following data in the meta data field: store ID, POS payment id, POS merchant id)

🚧

Prevent duplicate payment requests

If a connection error occurs, you can safely repeat the request without risk of creating a second object or performing the update twice.

To perform an idempotent request, provide an additional Idempotency-Key element to the request options.
For more information go to the Idempotent Requests page.

Initiate a Refund

To initiate a payment, use the device ID you received from the response of device list.

View the partner API: Initiate Payment

The transaction must be refunded on the terminal where the original sale occurred. Use the transactionId query parameter to identify this terminal.

Ensure the terminal is currently connected before proceeding with the refund.

Abort payment

In the case where you have sent the wrong amount / details or sent the payment to the wrong terminal, you can use do the following.

View the partner API: Abort Payment

There are two ways to abort a payment

1. Click 'cancel' on payment terminal , in the tap card screen.
2. Use the partner API: Abort Payment

🚧

Communicate result

It is important to communicate the result in a clear manner to the merchant on the POS screen. In case the payment cancellation failed, merchant can take action to either refund the payment or send the cancelation to the right device, depend on the received response .

Payment result

There are two ways to receive a payment result.

1. Poll the GET payment status endpoint.
2. Subscribe to payment notification webhook

To see the data fields associated to a payment go to the payment model page.

Error handling

Please refer to this page to read more about possible errors and recommended ways to handle them.

Sandbox testing

Initiating a payment in sandbox environment will prompt an emulator in the terminal allowing you to test successful vs failed transactions.