Sumup.Client (Sumup v1.0.0)

Copy Markdown View Source

Low-level HTTP transport shared by every Sumup.* resource module.

You should not need to call this module directly unless you're implementing support for a new/undocumented SumUp endpoint — every documented resource is already exposed through its own module (e.g. Sumup.Checkouts, Sumup.Readers).

Responsibilities:

  • Builds requests against Sumup.Config.t/0's :base_url with the correct authorization and accept headers (SumUp mixes RFC 9457 Problem Details and legacy error bodies across endpoints, so we always send Accept: application/problem+json, application/json as SumUp's own docs recommend for non-official clients).
  • Emits :telemetry spans per Sumup.Telemetry.
  • Retries 429/5xx/transport errors with exponential backoff and jitter, honoring a numeric retry-after header when present.
  • Normalizes every non-2xx response and transport failure into a Sumup.Error.

Summary

Types

method()
request_opts()

Functions

request(config, method, path, opts \\ [])

Sends a request and returns {:ok, decoded_body} or {:error, Sumup.Error.t()}.

Types

method()

@type method() :: :get | :post | :put | :patch | :delete

request_opts()

@type request_opts() :: [
  query: map() | keyword(),
  json: map() | nil,
  headers: [{String.t(), String.t()}],
  as: :json | :text,
  resource: atom(),
  operation: atom()
]

Functions

request(config, method, path, opts \\ [])

@spec request(Sumup.Config.t(), method(), String.t(), request_opts()) ::
  {:ok, term()} | {:error, Sumup.Error.t()}

Sends a request and returns {:ok, decoded_body} or {:error, Sumup.Error.t()}.

decoded_body is a plain map/list (already JSON-decoded) when as: :json (the default), or a raw string when as: :text (used by Sumup.Payouts when requesting the CSV report format). Resource modules are responsible for turning maps into their typed structs.