Daraja.C2B (daraja v0.1.0)

Copy Markdown View Source

Customer to Business (C2B) — receive payment notifications for Paybill or Till numbers.

Register URLs

Register your confirmation and (optional) validation callback URLs:

client = Daraja.Client.new()

Daraja.C2B.register_url(client, %{
  short_code: "600984",
  response_type: "Completed",
  confirmation_url: "https://example.com/c2b/confirmation",
  validation_url: "https://example.com/c2b/validation"
})

response_type controls what M-PESA does when your validation URL is unreachable:

  • "Completed" — M-PESA completes the transaction automatically.
  • "Cancelled" — M-PESA cancels the transaction automatically.

Simulate (sandbox only)

Simulate a C2B payment in the sandbox environment:

Daraja.C2B.simulate(client, %{
  short_code: "600984",
  command_id: "CustomerPayBillOnline",
  amount: 100,
  msisdn: "254708374149",
  bill_ref_number: "INV-001"
})

Handle Callbacks

Parse inbound validation and confirmation payloads posted by M-PESA to your registered URLs. See Daraja.C2B.Callback for details.

Summary

Types

result()

Functions

register_url(client, request)

Registers callback URLs for C2B payment notifications.

simulate(client, request)

Simulates a C2B payment transaction. Sandbox only — not supported in production.

Types

result()

@type result() ::
  {:ok, Daraja.C2B.Response.Success.t()}
  | {:error, :invalid_request, list()}
  | {:error, :auth_failed, Daraja.APIError.t()}
  | {:error, :http_error, Daraja.APIError.t() | term()}
  | {:error, :request_failed,
     Daraja.C2B.Response.Error.t() | Daraja.APIError.t()}

Functions

register_url(client, request)

@spec register_url(Daraja.Client.t(), map() | Daraja.C2B.RegisterUrlRequest.t()) ::
  result()

Registers callback URLs for C2B payment notifications.

Required params: short_code, response_type, confirmation_url, validation_url.

response_type must be "Completed" or "Cancelled" (sentence case).

Note: In production this is a one-time registration. To change URLs, delete them via the M-PESA Org portal and re-register.

simulate(client, request)

@spec simulate(Daraja.Client.t(), map() | Daraja.C2B.SimulateRequest.t()) :: result()

Simulates a C2B payment transaction. Sandbox only — not supported in production.

Required params: short_code, command_id, amount, msisdn. Optional params: bill_ref_number.

command_id must be "CustomerPayBillOnline" or "CustomerBuyGoodsOnline".