ElixirMpesa.Client (ElixirMpesa v0.2.0)

View Source

The HTTP layer: a thin, TLS-verifying Req wrapper.

Retry safety

Payment operations are not idempotent. A gateway timeout on c2bPayment often means the payment went through and only the response was lost, so retrying it automatically would risk charging a customer twice. This module therefore retries only read-only GET operations.

To retry a payment safely, resend it with the same "input_ThirdPartyConversationID" — M-Pesa treats that as the idempotency key and rejects the duplicate rather than processing it twice.

Testing

Pass req_options: [plug: {Req.Test, ElixirMpesa.Client}] to serve requests from a stub with no network access. See Testing.

Summary

Functions

connect_options()

The connection options every request uses.

request(config, method, path, params, session_key, opts \\ [])

Issues a request and normalises the result into {:ok, Response.t()} or {:error, Error.t()}.

Functions

connect_options()

@spec connect_options() :: keyword()

The connection options every request uses.

Exposed so the TLS posture is testable. Certificate verification is on: an earlier release of this library disabled it, which meant the encrypted API key and bearer session token travelled over connections that were never authenticated.

request(config, method, path, params, session_key, opts \\ [])

@spec request(
  ElixirMpesa.Config.t(),
  :get | :post | :put,
  String.t(),
  map(),
  String.t(),
  keyword()
) ::
  {:ok, ElixirMpesa.Response.t()} | {:error, ElixirMpesa.Error.t()}

Issues a request and normalises the result into {:ok, Response.t()} or {:error, Error.t()}.

method is :get, :post or :put. GET parameters go in the query string, which is what the M-Pesa API expects for its query endpoints; POST and PUT bodies are sent as JSON.