Builds and sends requests to the Moov API.

Every Moov.* resource module (Moov.Accounts, Moov.Transfers, ...) is a thin, documented wrapper around this module - you can always drop down to request/4 directly for an endpoint that doesn't have a dedicated wrapper yet, or to pass low-level options none of the wrappers expose.

Creating a client

# explicit credentials
client = Moov.Client.new(public_key: "...", private_key: "...")

# or pull defaults from `config :moov, ...` (see `Moov.Config`)
client = Moov.Client.new()

# client-side / Moov.js flows authenticate with a bearer token instead
client = Moov.Client.new(access_token: token)

A Moov.Client is a plain, immutable struct - hold on to it, store it in a GenServer's state, build a fresh one per request, whatever suits your application. Nothing about this library requires a singleton or an OTP application tree.

Sending requests

Moov.Client.get(client, "/accounts/#{account_id}")
Moov.Client.post(client, "/accounts", %{account_type: "individual", ...})
Moov.Client.patch(client, "/accounts/#{account_id}", %{profile: ...})
Moov.Client.delete(client, "/accounts/#{account_id}")

All of these (and request/4 itself) return {:ok, body} on any 2xx response or {:error, %Moov.Error{}} otherwise. body is the decoded JSON response with its original camelCase string keys, exactly as Moov sent it. Raise instead of pattern matching with Moov.unwrap!/1.

Request options

Every sending function accepts:

• :query - a map or keyword list of query string parameters
• :headers - a list of {name, value} tuples to merge in (these win over any header this module sets, except where noted)
• :idempotent - when true and no :idempotency_key is given, a random UUID v4 is generated once and reused across all retry attempts for this call. Moov.Transfers.create/3 sets this for you
• :idempotency_key - an explicit X-Idempotency-Key value, e.g. one derived from your own job/event ID so retries across process restarts stay deduplicated too
• :wait_for - set to "rail-response" to add the X-Wait-For header Moov's transfer/refund endpoints use to opt into a slower, fully populated synchronous response
• :form_multipart - for multipart file uploads (Moov.Files, Moov.Images, dispute evidence), e.g. form_multipart: [file: {binary, filename: "id.png", content_type: "image/png"}]. Mutually exclusive with :json for a given call
• :api_version, :max_retries, :receive_timeout - per-call overrides of the client's defaults