MpesaElixir.C2b (MpesaElixir v0.2.1)
Provides functionality for integrating with Safaricom's M-PESA Customer to Business (C2B) API. This module enables businesses to receive payments from customers directly to their M-PESA accounts through register_urls functionality that configures callback URLs for payment notifications.
C2B allows businesses to register validation and confirmation URLs that receive real-time notification of payments made to their paybill or till numbers, enabling automated payment processing and reconciliation.
Summary
Functions
Registers callback URLs for M-PESA C2B payment notifications.
Functions
@spec register_urls(MpesaElixir.C2b.RegisterRequest.t()) :: {:ok, map()} | {:error, String.t()}
Registers callback URLs for M-PESA C2B payment notifications.
This function configures the validation and confirmation URLs that will receive real-time notifications when customers make payments to your paybill or till number. These URLs must be publicly accessible HTTPS endpoints that can receive and process the payment data.
Parameters
request
- ARegisterRequest
struct containing:short_code
- Your M-PESA till or paybill numberresponse_type
- The type of response expected:"Completed"
- Payments are automatically completed after confirmation"Cancelled"
- Payments may be validated before completion
confirmation_url
- The HTTPS URL that receives payment confirmation datavalidation_url
- The HTTPS URL that receives payment validation requests
Response
Returns {:ok, response}
on success where response
is a map containing:
"ConversationID"
- A unique identifier for the API request"OriginatorCoversationID"
- A unique identifier for the transaction"ResponseDescription"
- A description of the operation result
Returns {:error, reason}
on failure.
Examples
iex> request = %MpesaElixir.C2b.RegisterRequest{
...> short_code: "600000",
...> response_type: "Completed",
...> confirmation_url: "https://example.com/mpesa/confirmation",
...> validation_url: "https://example.com/mpesa/validation"
...> }
iex> MpesaElixir.C2b.register_urls(request)
{:ok, %{
"ConversationID" => "AG_20230815_1234567890abcdef",
"OriginatorCoversationID" => "12345-67890-1",
"ResponseDescription" => "Success. Request accepted for processing"
}}
Notes
- Both URLs must be secure (HTTPS) and publicly accessible
- The validation URL receives requests before payment completion and can accept/reject them
- The confirmation URL receives notification after a successful payment
- Response type "Completed" is recommended for most use cases to simplify the payment flow
- If your URLs change, you need to re-register them using this API
- The endpoints will receive JSON payloads with transaction details