# `Daraja.HTTPClient`
[🔗](https://github.com/okothkongo/daraja/blob/v0.1.1/lib/daraja/http_client.ex#L1)

Behaviour for making HTTP requests.

Library users can implement this behaviour to provide a custom HTTP client,
or rely on the default `Daraja.HTTPClient.Finch` implementation.

The default implementation is `Daraja.HTTPClient.Finch`, which requires
`{:finch, "~> 0.23"}` in your `mix.exs` and a Finch pool (default name
`Daraja.Finch`) started in your supervision tree. CI verifies compatibility
from Finch 0.23.0 through the latest `~> 0.23` release. If you configure a
custom client, both requirements can be dropped.

Configure the adapter in your application:

    config :daraja, :http_client, MyApp.CustomHTTPClient

## TLS

The default Finch adapter verifies Safaricom endpoints using the host OS
trust store (standard CA validation). Certificate pinning is not built in;
use a custom `Daraja.HTTPClient` implementation when your deployment requires
pinned certificates or other TLS hardening.

## Custom client security

This behaviour specifies only the `request/4` return shape. Custom
implementations must verify TLS peers, avoid logging credentials or full
request bodies (especially STK `Password` fields), use bounded timeouts, and
not follow redirects to unintended hosts. See `Daraja.HTTPClient.Compliance`
for a checklist you can use when reviewing or testing custom adapters.

# `body`

```elixir
@type body() :: binary()
```

# `headers`

```elixir
@type headers() :: [{String.t(), String.t()}]
```

# `method`

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

# `status`

```elixir
@type status() :: 100..599
```

# `request`

```elixir
@callback request(method(), url :: String.t(), headers(), body()) ::
  {:ok, status(), headers(), body()} | {:error, term()}
```

---

*Consult [api-reference.md](api-reference.md) for complete listing*