API tutorials

The following sections show the basic usage of each endpoint in the REST Pay API.

Required request data

The endpoints comprising the API require one or more headers to successfully complete a request. Use the following table to determine the header or headers needed for a request.

All requests support the following:

HeaderRequired?
X-Clover-Device-IdRequired
X-POS-IdRequired
Idempotency-KeyRequired for financial operations

Idempotent requests

Some request types require an Idempotency-Key header to guard against a transaction being accidentally repeated. This is useful when an API call is disrupted in transit and a response is not returned. For example, if a request to create a charge does not respond due to a network connection error, you can retry the request with the same idempotency key to guarantee that no more than one charge is created.

The request types that require an Idempotency-Key header are refund, payment, charge, and capture.

Idempotency-Key: {your key}

All requests support the idempotency header, but it is required for financial operations:

  • /v1/credits
  • /v1/payments
  • /v1/payments/{paymentId}/capture
  • /v1/payments/{paymentId}/increment
  • /v1/payments/{paymentId}/refunds
  • /v1/payments/{paymentId}/tip-adjust
  • /v1/payments/{paymentId}/void

Identifying the target device

The REST Pay API provides interaction with physical Clover devices, so your POS must specify the device meant to process a request. To do this, set the X-Clover-Device-Id header with the serial number of the device which you can find in the Setup app on the device or from the web dashboard.

X-Clover-Device-Id: {your device id}

If the provided ID does not match the device's serial number, an error message is returned (the status code for the error is 400 Bad Request).

{
    "code": "processing_error",
    "message": "Device serial number does not match X-Clover-Device-Id",
    "type": "api_error"
}

Identifying the POS to Clover systems

If you want to record which POS sent a request, include a X-POS-ID header with a value of your choice.

X-POS-ID: {your POS name}

Locating UUIDs

If you need your app, developer, or test merchant UUID, you can get that information by logging on to the developer dashboard. These IDs are different in sandbox and production, so ensure you are logged in to the correct environment:

Locating an app UUID

Each of your app's basic information is shown in a card on the developer dashboard. The app UUID is the thirteen-character value under the app name.

The app settings page also shows the UUID.

Locating your developer UUID

To view your developer ID, from the account menu in the top right, select Developer Settings. On the settings page, the ID appears in the Developer Info section.

Locating your test merchant's UUID

To view your merchant ID, select the test merchant from the dashboard drop-down list. On the side-nav, select Setup > Merchants. On the Account Settings page, the ID appears in the Merchant column under the merchant name.


Did this page help you?