REST Pay Display API tutorials

The REST Pay Display tutorials display the basic usage of each endpoint in the REST Pay Display API.

Required request data

The endpoints of 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:

Idempotent requests

Some request types require an Idempotency-Key header to safeguard against accidentally repeating a transaction. This is useful when an API call is disrupted in transit and a response is not returned. 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

📘

NOTE

To learn more, see our blog post Fiddling Through Digital Keys: Clover Auth Tokens and Ecommerce Keys.

Identify the target device serial number

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

X-Clover-Device-Id: {your device serial number}

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"
}

Identify 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}

Locate unique identifiers (UUIDs)

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

• Sandbox developer dashboard
• Production developer dashboard

Locate an app UUID

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

The app settings page also displays the UUID.

Locate 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.

Locate your test merchant UUID

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

End customer transactions

End your customer transactions with a call to the Welcome or Thank You screen; otherwise, the spinning icon remains on the screen until another action is taken.