Sumup.Config (Sumup v1.0.0)

Copy Markdown View Source

Validated configuration for a Sumup client.

Build a config once (typically at application boot, or per-request if you serve multiple SumUp merchants from one app) and pass it to every resource function:

config = Sumup.Config.new!(api_key: {:system, "SUMUP_API_KEY"})
{:ok, checkout} = Sumup.Checkouts.get(config, "checkout_id")

Options

  • :api_key (String.t() or {:system, String.t()} or {module(), atom(), list()}) - Your SumUp secret API key (sk_live_... / sk_test_...), or a restricted key. Mutually exclusive with :access_token -- if both are given, :access_token wins. Accepts a raw string, a {:system, "ENV_VAR"} tuple resolved at config-build time, or an {module, function, args} tuple for e.g. secrets managers.

  • :access_token (String.t() or {:system, String.t()} or {module(), atom(), list()}) - An OAuth2 access token, resolved the same way as :api_key.

  • :base_url (String.t/0) - API base URL. Override for testing against a mock server. The default value is "https://api.sumup.com".

  • :receive_timeout (pos_integer/0) - Response timeout in ms. The default value is 30000.

  • :connect_timeout (pos_integer/0) - Connection timeout in ms. The default value is 10000.

  • :max_retries (non_neg_integer/0) - Max retry attempts for retryable errors (429 and 5xx). The default value is 3.

  • :retry_base_delay (pos_integer/0) - Base delay in ms for exponential backoff (doubles per attempt, with jitter). The default value is 250.

  • :retry_max_delay (pos_integer/0) - Maximum backoff delay in ms. The default value is 5000.

  • :telemetry_prefix (list of atom/0) - Prefix used for :telemetry.span/3 events, see Sumup.Telemetry. The default value is [:sumup].

  • :user_agent (String.t/0) - Override the User-Agent header.

  • :req_options (keyword/0) - Extra options merged into every Req.new/1 call (e.g. :plug for testing, :finch pool name). The default value is [].

  • :finch_pool (atom/0) - Name of a Finch pool to use instead of the default one.

Summary

Types

auth()
t()

Functions

new(opts)

Builds a config, returning {:ok, config} or {:error, exception}.

new!(opts)

Builds a config, raising NimbleOptions.ValidationError on invalid input.

Types

auth()

@type auth() ::
  {:system, String.t()}
  | {:system, String.t(), String.t()}
  | {module(), atom(), list()}
  | String.t()

t()

@type t() :: %Sumup.Config{
  access_token: String.t() | nil,
  api_key: String.t() | nil,
  base_url: String.t(),
  connect_timeout: pos_integer(),
  finch_pool: atom() | nil,
  max_retries: non_neg_integer(),
  receive_timeout: pos_integer(),
  req_options: keyword(),
  retry_base_delay: pos_integer(),
  retry_max_delay: pos_integer(),
  telemetry_prefix: [atom()],
  user_agent: String.t()
}

Functions

new(opts)

@spec new(keyword()) :: {:ok, t()} | {:error, Exception.t()}

Builds a config, returning {:ok, config} or {:error, exception}.

new!(opts)

@spec new!(keyword()) :: t()

Builds a config, raising NimbleOptions.ValidationError on invalid input.