MishkaPay.Client (Mishka Pay v0.0.1)

Copy Markdown View Source

The HTTP base every provider adapter builds on, over Req. A request is described as this guarded_struct and sent with request/1:

MishkaPay.Client.request(%{
  provider: "stripe",
  method: :post,
  base_url: "https://api.stripe.com",
  path: "/v1/refunds",
  auth: {:bearer, keys.secret_key},
  headers: %{"stripe-version" => "2026-10-28"},
  form: [payment_intent: "pi_123"],
  idempotency_header: "idempotency-key"
})

What every provider gets from it:

  • Retries. A network error and the answers 408, 429, 500, 502, 503 and 504 are tried again, max_retries times (2 by default). The wait is what a whole-second Retry-After header says, or retry_delay milliseconds (500 by default) doubled on each try, and never more than max_wait milliseconds (ten seconds by default). A write (post, put, patch, delete) is tried again only when the provider takes an idempotency key, so a payment is never made twice.
  • The provider's own word on a retry. With retry_header set (Stripe's "stripe-should-retry"), an answer carrying it decides: true tries again even a status that is not on the list above (a lock held a moment too long), false never tries again. A write without its idempotency key is still never sent twice.
  • Why the rate was limited. With limit_header set (Stripe's "stripe-rate-limited-reason"), its value is the :rate_limit_reason of the telemetry below, so a site can tell a burst of its own from a limit on one endpoint.
  • One idempotency key per call. When idempotency_header is set, a write carries the key in that header: idempotency_key when the caller gives one (derived from its own operation, so a repeated call is the same call), a random one otherwise. Every retry sends the same key.
  • Telemetry. [:mishka_pay, :request, :start | :stop | :exception], with :provider, :method, :path and :idempotency_key, and :status on :stop; and [:mishka_pay, :request, :retry] before each retry, with the :wait in milliseconds, the :attempt, the :status or network :reason, the :retry_after the provider asked for and its :rate_limit_reason. :stop carries the :rate_limit_reason of the last answer too (nil when it gave none). Never a key or a body.

request/1 answers {:ok, %Req.Response{}} for any HTTP status: the adapter reads its provider's own error body. A request that never got an answer is a MishkaPay.Errors.Unreachable error, and a description that is not valid an :invalid one. inspect/1 leaves out :auth. headers, params, form and json reach the provider as given: their keys are never turned into atoms.

base_url is an http or https address with no user, query or fragment, and path one plain path from /: no query (params carries it), no control character, dot segment or encoded slash. So a path can never send the request, and its auth, to another host or place. Header names are compared without case.

The body is one of form, json, json_text or multipart. json_text is a JSON document already encoded, sent byte for byte: for a provider that checks a message it signed against the exact bytes it sent, such as PayPal's webhook verification. multipart sends multipart/form-data, the way a file is uploaded: a list of {name, value} parts, where a value is a binary, or {binary, filename: "receipt.pdf", content_type: "application/pdf"} for a file. A value is always bytes in memory, never a path or a stream, so a request never reads a file from disk.

:options takes any other Req option, such as plug: {Req.Test, MyTest} in a test, on top of config :mishka_pay, req_options: [...] (see MishkaPay.Test.stub_http/1). It cannot change what this module decides: the method, address, headers, auth, body, retries and timeout.

Summary

Types

t()

The struct that builder/1 returns.

Functions

A sample %MishkaPay.Client{} populated from defaults + type-based fallbacks.

Sends the request attrs describe. See the module doc for what it answers.

Types

t()

@type t() :: %MishkaPay.Client{
  auth: term() | nil,
  base_url: String.t(),
  form: (map() | keyword()) | nil,
  headers: map() | nil,
  idempotency_header: String.t() | nil,
  idempotency_key: String.t() | nil,
  json: (map() | list()) | nil,
  json_text: String.t() | nil,
  limit_header: String.t() | nil,
  max_retries: non_neg_integer() | nil,
  max_wait: non_neg_integer() | nil,
  method: (:get | :post | :put | :patch | :delete) | nil,
  multipart: term() | nil,
  options: keyword() | nil,
  params: (map() | keyword()) | nil,
  path: String.t(),
  provider: String.t(),
  receive_timeout: pos_integer() | nil,
  retry_delay: non_neg_integer() | nil,
  retry_header: String.t() | nil
}

The struct that builder/1 returns.

FieldTypeRequiredDefaultDescriptionDerives
:providerString.t()yesvalidate(not_nil_value, string, not_empty)
:method:get | :post | :put | :patch | :delete | nilno:getvalidate(not_nil_value, enum=Atom[get::post::put::patch::delete])
:base_urlString.t()yessanitize(trim) validate(not_nil_value, string, not_empty)<br>validator {MishkaPay.Client, :base_url}
:pathString.t()yesvalidate(not_nil_value, string, not_empty)<br>validator {MishkaPay.Client, :path}
:authterm() | nilno
:headersmap() | nilno%{}validate(map)
:paramsmap() | keyword() | nilnovalidate(either=[map, list])<br>validator {MishkaPay.Client, :params}
:formmap() | keyword() | nilnovalidate(either=[map, list])
:jsonmap() | list() | nilnovalidate(either=[map, list])
:json_textString.t() | nilnovalidate(string, not_empty)
:multipartterm() | nilnovalidator {MishkaPay.Client, :multipart}
:idempotency_headerString.t() | nilnosanitize(trim, downcase) validate(string, not_empty)
:idempotency_keyString.t() | nilnovalidate(string, not_empty)
:retry_headerString.t() | nilnosanitize(trim, downcase) validate(string, not_empty)
:limit_headerString.t() | nilnosanitize(trim, downcase) validate(string, not_empty)
:max_retriesnon_neg_integer() | nilno2validate(integer, min_len=0)
:retry_delaynon_neg_integer() | nilno500validate(integer, min_len=0)
:max_waitnon_neg_integer() | nilno10000validate(integer, min_len=0)
:receive_timeoutpos_integer() | nilno30000validate(integer, min_len=1)
:optionskeyword() | nilno[]validate(list)

Functions

builder(attrs_or_input, error \\ false)

enforce_keys()

enforce_keys(field)

example()

A sample %MishkaPay.Client{} populated from defaults + type-based fallbacks.

keys()

keys(field)

request(attrs)

@spec request(map()) :: {:ok, Req.Response.t()} | {:error, Splode.Error.t()}

Sends the request attrs describe. See the module doc for what it answers.