Clover Terminal Payments

Collect card-present payments on a Clover terminal. Synapto routes a payment intent to a device, the customer taps, inserts, or swipes their card on the terminal, and the payment is processed without your application ever handling card details.

Devices are physical Clover terminals. They're added to your account by connecting your Clover account in the Dashboard → Account Settings → Connect Clover — Synapto then creates a device for each of your Clover terminals automatically. Once connected, your terminals appear in ListDevices and can accept payments.

Terminal payments use the same payment intent resource as online payments. The only difference is how the intent is confirmed: instead of collecting a card in the browser, you send the intent to a device.

Listing devices

API reference

List the devices associated with your account to find a terminal to take a payment on. A device must be in the ACTIVE state to accept payments.

curl -X POST https://api.synaptopay.com/v1/accounts/acct_YOUR_ACCOUNT/devices:list \
  -H "Authorization: Api-Key $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

{
  "devices": [
    {
      "name": "accounts/acct_YOUR_ACCOUNT/devices/dvc_DEVICE_ID",
      "state": "ACTIVE",
      "model": "CLOVER_FLEX",
      "display_name": "Front counter",
      "serial_number": "C123UQ45670089",
      "supported_payment_rails": ["card"],
      "supported_currency_codes": ["GBP"],
      "create_time": "2025-11-17T16:49:39Z",
      "update_time": "2025-11-17T16:49:39Z"
    }
  ]
}

Device fields

Taking a payment on a device

API reference

To collect a payment on a terminal, create a payment intent with confirm set to true and device set to the resource name of an ACTIVE device. When device is set, any payment_method is ignored — the card is captured on the terminal itself.

The Idempotency-Key header lets you safely retry the request if it fails — see Idempotency.

curl -X POST https://api.synaptopay.com/v1/accounts/acct_YOUR_ACCOUNT/payment-intents \
  -H "Authorization: Api-Key $API_KEY" \
  -H "Idempotency-Key: YOUR_UNIQUE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "10000",
    "currency": "GBP",
    "confirm": true,
    "device": "accounts/acct_YOUR_ACCOUNT/devices/dvc_DEVICE_ID"
  }'

The intent is returned in the PROCESSING state and the payment prompt appears on the terminal for the customer to complete:

{
  "name": "accounts/acct_YOUR_ACCOUNT/payment-intents/pi_PAYMENT_INTENT_ID",
  "amount": "10000",
  "currency": "GBP",
  "state": "PROCESSING",
  "device": "accounts/acct_YOUR_ACCOUNT/devices/dvc_DEVICE_ID",
  "client_secret": "pi_PAYMENT_INTENT_ID_secret_SECRET",
  "create_time": "2025-11-17T16:49:39Z",
  "update_time": "2025-11-17T16:49:39Z"
}

📘

The payment_method on the returned intent should be ignored until the payment succeeds. Only once the intent reaches SUCCEEDED does it reflect the actual card used on the device.

Tracking the result

The customer completes the payment on the terminal, so your application needs to wait for the outcome.

Listen for a webhook

As with online payments, listen for the payment_intent.succeeded webhook event to confirm the payment on your server. See Webhooks for setup instructions.

Poll the payment intent

An alternative to waiting for a webhook is to poll GetPaymentIntent until the intent leaves the PROCESSING state:

curl https://api.synaptopay.com/v1/accounts/acct_YOUR_ACCOUNT/payment-intents/pi_PAYMENT_INTENT_ID \
  -H "Authorization: Api-Key $API_KEY"

• SUCCEEDED — the payment completed on the device. The intent's payment_method and latest_charge now reflect the card that was used.
• REQUIRES_PAYMENT_METHOD — the device operation failed (for example, the customer cancelled on the terminal or the card was declined). The intent reverts to REQUIRES_PAYMENT_METHOD with last_payment_error populated, and last_payment_error.device set to the device that failed. You can retry by confirming the same intent on a device again.

Payment intent states

Terminal payments move through the same payment intent states as online payments: