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_retriestimes (2 by default). The wait is what a whole-secondRetry-Afterheader says, orretry_delaymilliseconds (500 by default) doubled on each try, and never more thanmax_waitmilliseconds (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_headerset (Stripe's"stripe-should-retry"), an answer carrying it decides:truetries again even a status that is not on the list above (a lock held a moment too long),falsenever tries again. A write without its idempotency key is still never sent twice. - Why the rate was limited. With
limit_headerset (Stripe's"stripe-rate-limited-reason"), its value is the:rate_limit_reasonof 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_headeris set, a write carries the key in that header:idempotency_keywhen 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,:pathand:idempotency_key, and:statuson:stop; and[:mishka_pay, :request, :retry]before each retry, with the:waitin milliseconds, the:attempt, the:statusor network:reason, the:retry_afterthe provider asked for and its:rate_limit_reason.:stopcarries the:rate_limit_reasonof the last answer too (nilwhen 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
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
@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.
| Field | Type | Required | Default | Description | Derives |
|---|---|---|---|---|---|
:provider | String.t() | yes | validate(not_nil_value, string, not_empty) | ||
:method | :get | :post | :put | :patch | :delete | nil | no | :get | validate(not_nil_value, enum=Atom[get::post::put::patch::delete]) | |
:base_url | String.t() | yes | sanitize(trim) validate(not_nil_value, string, not_empty)<br>validator {MishkaPay.Client, :base_url} | ||
:path | String.t() | yes | validate(not_nil_value, string, not_empty)<br>validator {MishkaPay.Client, :path} | ||
:auth | term() | nil | no | |||
:headers | map() | nil | no | %{} | validate(map) | |
:params | map() | keyword() | nil | no | validate(either=[map, list])<br>validator {MishkaPay.Client, :params} | ||
:form | map() | keyword() | nil | no | validate(either=[map, list]) | ||
:json | map() | list() | nil | no | validate(either=[map, list]) | ||
:json_text | String.t() | nil | no | validate(string, not_empty) | ||
:multipart | term() | nil | no | validator {MishkaPay.Client, :multipart} | ||
:idempotency_header | String.t() | nil | no | sanitize(trim, downcase) validate(string, not_empty) | ||
:idempotency_key | String.t() | nil | no | validate(string, not_empty) | ||
:retry_header | String.t() | nil | no | sanitize(trim, downcase) validate(string, not_empty) | ||
:limit_header | String.t() | nil | no | sanitize(trim, downcase) validate(string, not_empty) | ||
:max_retries | non_neg_integer() | nil | no | 2 | validate(integer, min_len=0) | |
:retry_delay | non_neg_integer() | nil | no | 500 | validate(integer, min_len=0) | |
:max_wait | non_neg_integer() | nil | no | 10000 | validate(integer, min_len=0) | |
:receive_timeout | pos_integer() | nil | no | 30000 | validate(integer, min_len=1) | |
:options | keyword() | nil | no | [] | validate(list) |
Functions
A sample %MishkaPay.Client{} populated from defaults + type-based fallbacks.
@spec request(map()) :: {:ok, Req.Response.t()} | {:error, Splode.Error.t()}
Sends the request attrs describe. See the module doc for what it answers.