Payments (semi) integration FAQs

How can I integrate my website with a Clover Mini device using a sandbox account?

To integrate your website with a Clover Mini device in the sandbox environment, you’ll need to use the REST Pay Display API. This API allows your web app to connect to Clover devices like the Mini for semi-integrated payment flows. Since you don’t have physical access to the Mini device, you can use a Dev Kit or an Android emulator with the Mini hardware profile for testing. Note that some hardware-specific feature, such as NFC or printing may not be fully supported in the emulator.

Steps to get started:

Create a sandbox developer account and a test merchant on the Global Developer Dashboard.
Create a semi-integrated app and generate a Remote App ID (RAID) in your app settings; this is required for the device to trust your web request.
On-Device: Open the App Market on your Mini (or emulator) and install the REST Pay Display app. It must be running in the foreground to receive "Ping" or "Sale" requests. Use the endpoint format: https://apisandbox.dev.clover.com/connect/v1/device/ping>; Add /connect after the base URL for all API calls.

Can I use Secure Network Pay Display for commercial payments in a semi-integrated Android kiosk setup?

Yes, you can use the Secure Network Pay Display (SNPD) for commercial payments in a semi-integrated Android kiosk environment. While it's commonly used during development, it is also suitable for production use. Other pay display options are:

USB Pay Display: For fixed, hard-wired connections (specifically for Clover Mini).
Cloud Pay Display: For environments where the POS and Clover device cannot be on the same local network or require terminal portability.
REST Pay Display API: For web-based or high-level integrations using WebSockets.

Why am I getting an Unauthorized response when trying to connect to a Clover device using the Pay Display API in production?

In production, an Unauthorized (401) response typically indicates that the request could not be authenticated due to credentials, permissions, or configuration mismatches. While your merchant access token may allow you to list devices, additional permissions are required to interact with them through endpoints, such as /connect/v1/device/read-confirmation. To resolve this:

Ensure your app has all required permissions, especially those related to device and payment interactions, such as Merchant Read and specific Payments permissions.
Use production base URL https://api.clover.com and a production-generated OAuth token tied to the correct merchant account.
Ensure the Remote Application ID is valid and approved for production.
For card-present transactions, the merchant account must have the paymentDeviceConfiguration enabled. In the REST Pay Display API, verify that the merchant's allow_payment_device_configuration field is true.

If you're using a test merchant, email [email protected] to request updates to your merchant settings.

Why am I getting Authentication successful, but no Remote Application ID has been configured for Application when using the REST Pay Display API in sandbox?

This error typically occurs when the Remote Application ID (RAID) is not properly configured or recognized by the Clover system, even if authentication is successful. Here are the steps to troubleshoot:

To troubleshoot:

Step 1: Verify App Type configuration:

Log in to your Sandbox Developer Dashboard.
Go to Your Apps > [App Name] > App Settings.
Click App Type.
Ensure Web is selected under the REST Clients section.
For "Is this an integration with an existing point of sale option?", select Yes.

The RAID is generated here. Copy the 13-character string labeled Remote App ID.

Step 2: Check your Request headers: The REST Pay Display API requires the RAID to be passed in a specific header. Ensure your request includes:

X-Clover-Device-Id: The serial number of your Clover device.
X-POS-Id: This is where you must provide your Remote Application ID (RAID).

Step 3: Confirm Pay Display app Installation: Your physical Dev Kit or Emulator must have the correct "listener" app active:

For Cloud connections: Cloud Pay Display must be installed and open.
For Local network connections: Secure Network Pay Display must be installed and open. If the app isn't on the device, the RAID cannot register with a listener.

Step 4: Token type check: Ensure you are using an OAuth-generated access token. Merchant API Tokens (generated in the merchant dashboard) are often restricted and may cause identification issues with the REST Pay Display API.

If the issue persists, email [email protected] with your RAID, Dev Kit serial number, and developer account details.

How can a Windows-based POS system semi-integrate with the Flex 3?

Use the Remote Pay Windows SDK, which supports .NET Framework 4.5 and works with the Flex through a USB or network. It allows your Windows POS to send sale requests and receive payment responses. Learn more:

How can I request a payment for an order using the REST Pay Display API?

The REST Pay Display API is a payment-only interface that is designed for initiating payment flows (sale, refund, preauth, auth) but does not support passing an order ID or item ID directly. It is not intended for full order management or inventory-linked transactions.

To request a payment you must specify the amount and transaction type, such as sale or auth. The API does not accept item-level or order-level references. You can optionally display custom messages or prompts on the Clover device during the transaction.

If you need to associate payments with specific items or orders, consider using the Order Display v1/device/display-order endpoint to show order details on the Clover device.

Updated 1 day ago