Readers

Initiates a payment on the SumUp Go terminal identified by the reader ID.

Use client_transaction_id as an idempotency key: retrying the request with the same value returns the result of the original payment instead of creating a duplicate.

OAuth scopes: Requires one of: payments, readers.write.

Required permissions:

• readers_checkout_create

List all readers of the merchant.

OAuth scopes: Requires one of: readers.read, terminals.read.

Required permissions:

• {"relation":"readers.list","object_type":"merchant","object_id_param":"merchant_code"}

Create a new Reader for the merchant account.

OAuth scopes: Requires one of: readers.write, terminals.write.

Required permissions:

• {"relation":"readers.create","object_type":"merchant","object_id_param":"merchant_code"}

Retrieve a Reader.

OAuth scopes: Requires one of: readers.read, terminals.read.

Required permissions:

• {"relation":"readers.view","object_type":"merchant","object_id_param":"merchant_code"}

Delete a reader.

OAuth scopes: Requires one of: readers.write, terminals.write.

Required permissions:

• {"relation":"readers.delete","object_type":"merchant","object_id_param":"merchant_code"}

Updates a reader's name or metadata and returns the updated reader.

Providing metadata replaces the entire metadata object; include all entries that should be retained. Omitted fields remain unchanged.

OAuth scopes: Requires one of: readers.write, terminals.write.

Required permissions:

• {"relation":"readers.update","object_type":"merchant","object_id_param":"merchant_code"}

Creates a Checkout for a Reader.

This process is asynchronous and the actual transaction may take some time to be started on the device.

There are some caveats when using this endpoint:

• The target device must be online, otherwise checkout won't be accepted
• After the checkout is accepted, the system has 60 seconds to start the payment on the target device. During this time, any other checkout for the same device will be rejected.

Note: If the target device is a Solo, it must be in version 3.3.24.3 or higher.

Optionally include an affiliate object to attach integrator metadata to the payment. Provide both app_id and key when including this object.

OAuth scopes: Requires one of: readers.write.

Required permissions:

• readers.checkouts.create

Provides the last known status for a Reader.

This endpoint allows you to retrieve updates from the connected card reader, including the current screen being displayed during the payment process and the device status (battery level, connectivity, and update state).

Supported States

• IDLE – Reader ready for next transaction
• SELECTING_TIP – Waiting for tip input
• WAITING_FOR_CARD – Awaiting card insert/tap
• WAITING_FOR_PIN – Waiting for PIN entry
• WAITING_FOR_SIGNATURE – Waiting for customer signature
• UPDATING_FIRMWARE – Firmware update in progress

Device Status

• ONLINE – Device connected and operational
• OFFLINE – Device disconnected (last state persisted)

Note: If the target device is a Solo, it must be in version 3.3.39.0 or higher.

OAuth scopes: Requires one of: readers.read.

Required permissions:

• readers.view

Returns the menu lock settings for a Solo reader.

For an online reader, returns the current settings. For an offline reader, returns the last saved settings, which may differ from its current configuration. Returns 404 if the reader is offline and no saved settings are available.

The response may include the menu lock PIN.

OAuth scopes: Requires one of: readers.read.

Required permissions:

• readers.checkouts.view

Updates the menu lock settings for a Solo reader. The reader must be online. A successful response confirms that the reader applied the update.

Include at least one of menu_lock.enabled or menu_lock.passcode. Omitted settings keep their current values. The response contains only the settings included in the request.

When enabling menu lock for a reader without a PIN, include a four-digit PIN in menu_lock.passcode in the same request.

OAuth scopes: Requires one of: readers.write.

Required permissions:

• readers.checkouts.create

Terminate a Reader Checkout stops the current transaction on the target device.

This process is asynchronous and the actual termination may take some time to be performed on the device.

There are some caveats when using this endpoint:

• The target device must be online, otherwise terminate won't be accepted
• The action will succeed only if the device is waiting for cardholder action: e.g: waiting for card, waiting for PIN, etc.
• There is no confirmation of the termination.

If a transaction is successfully terminated and return_url was provided on Checkout, the transaction status will be sent as failed to the provided URL.

Note: If the target device is a Solo, it must be in version 3.3.28.0 or higher.

OAuth scopes: Requires one of: readers.write.

Required permissions:

• readers.checkouts.delete

Get a Checkout for a Reader.

OAuth scopes: Requires one of: readers.read.

Required permissions:

• readers.checkouts.view