Readers: pair, manage, and push payments to physical SumUp Solo card
readers. API version v0.1.
Reader checkouts are asynchronous by design: checkout/4 returns as
soon as the charge has been pushed to the device (HTTP 201), carrying
a client_transaction_id. The actual card-present interaction happens
on the terminal itself, and completion is observed either via a webhook
(return_url) or by polling Sumup.Transactions.get/3 with that
client_transaction_id. This module intentionally does not fake
synchronicity by polling internally — do that explicitly in your own
code with whatever timeout policy fits your integration.
Summary
Functions
Pushes a checkout to a paired reader for the payer to complete on the
device. Returns immediately (HTTP 201) with client_transaction_id
for later reconciliation via Sumup.Transactions.get/3.
Unpairs (deletes) a reader.
Retrieves a single reader. Pass if_modified_since: (an HTTP-date or
ISO 8601 string) to get back {:ok, :not_modified} instead of a body
when the reader hasn't changed.
Fetches a reader's live device status (battery, firmware, connectivity).
Lists all readers paired to merchant_code.
Pairs a reader to merchant_code using the pairing_code shown on its
screen.
Cancels/terminates whatever checkout is currently in-flight on a reader.
Updates a reader's name and/or metadata.
Functions
@spec checkout(Sumup.Config.t(), String.t(), String.t(), keyword() | map()) :: {:ok, String.t()} | {:error, Sumup.Error.t()}
Pushes a checkout to a paired reader for the payer to complete on the
device. Returns immediately (HTTP 201) with client_transaction_id
for later reconciliation via Sumup.Transactions.get/3.
:total_amount(map/0) - Required.%{value:, minor_unit:, currency:}, seeSumup.Money.MinorUnit.:tip_rates(list offloat/0) - Suggested tip percentages offered to the payer on-device, e.g.[0.10, 0.15, 0.20].:tip_timeout(integer/0) - Seconds to wait for a tip selection before proceeding without one.:card_type- Restrict to a card type where supported.:installments(integer/0) - Number of installments, where supported.:description(String.t/0) - Shown on the reader/receipt.:return_url(String.t/0) - Webhook/callback target for the reader checkout result.:affiliate(map/0) -%{app_id:, foreign_transaction_id:, key:, tags:}for affiliate/marketplace attribution.:aade(map/0) -%{provider_id:, signature:, signature_data:}, Greek AADE e-receipt fiscalization data.
@spec delete(Sumup.Config.t(), String.t(), String.t()) :: :ok | {:error, Sumup.Error.t()}
Unpairs (deletes) a reader.
@spec get(Sumup.Config.t(), String.t(), String.t(), keyword()) :: {:ok, Sumup.Reader.t()} | {:ok, :not_modified} | {:error, Sumup.Error.t()}
Retrieves a single reader. Pass if_modified_since: (an HTTP-date or
ISO 8601 string) to get back {:ok, :not_modified} instead of a body
when the reader hasn't changed.
@spec get_status(Sumup.Config.t(), String.t(), String.t()) :: {:ok, Sumup.ReaderStatus.t()} | {:error, Sumup.Error.t()}
Fetches a reader's live device status (battery, firmware, connectivity).
@spec list(Sumup.Config.t(), String.t()) :: {:ok, [Sumup.Reader.t()]} | {:error, Sumup.Error.t()}
Lists all readers paired to merchant_code.
@spec pair(Sumup.Config.t(), String.t(), keyword() | map()) :: {:ok, Sumup.Reader.t()} | {:error, Sumup.Error.t()}
Pairs a reader to merchant_code using the pairing_code shown on its
screen.
:pairing_code(String.t/0) - Required. The code shown on the reader's display.:name(String.t/0) - Required. A friendly name for the reader.:metadata(map/0) - Free-form metadata you control.
@spec terminate(Sumup.Config.t(), String.t(), String.t()) :: :ok | {:error, Sumup.Error.t()}
Cancels/terminates whatever checkout is currently in-flight on a reader.
@spec update(Sumup.Config.t(), String.t(), String.t(), keyword() | map()) :: {:ok, Sumup.Reader.t()} | {:error, Sumup.Error.t()}
Updates a reader's name and/or metadata.
:name(String.t/0) - A new friendly name for the reader.:metadata(map/0) - Free-form metadata you control.