Pesapal
v0.1.1

Pesapal (Pesapal v0.1.1)

Handles integration with Pesapal payment gateway API (v3).

This module provides functions to authenticate, register IPN webhooks, initiate payments, and check transaction statuses with the Pesapal API.

The flow is as follows:

  1. Authenticate with Pesapal using authenticate/2.
  2. Register an IPN webhook using register_ipn/2.
  3. Initiate a payment using initiate_payment/6.
  4. Check the transaction status using check_transaction_status/2.
  5. Handle the IPN notifications sent to your webhook URL.

For your IPN webhook, you need to set up a route in your application to handle incoming POST requests from Pesapal. The IPN URL should be publicly accessible and should be able to process the incoming notifications. This can be a simple post endpoint in your application as follows

defmodule AppWeb.OrderController do
use AppWeb, :controller

def create(conn, params) do
  IO.inspect(params)

  # Handle the IPN notification here

  conn
  |> Plug.Conn.put_resp_content_type("application/json")
  |> Plug.Conn.send_resp(200, Jason.encode!(%{message: "Success"}))
end
end

# In your router.ex file, add a route for the IPN webhook

defmodule AppWeb.Router do
  use AppWeb, :router

  scope "/api", AppWeb do
    pipe_through :api

    post "/webhook", OrderController, :create
  end
end

configuration

 Configuration

You need to set the api_base_url in your application configuration , as well as your consumer key and consumer secret.

You can set this in your config file:

config :pesapal,
  api_base_url: "https://cybqa.pesapal.com/pesapalv3/api",
  consumer_key: "qkio1BGGYAXTu2JOfm7XSXNruoZsrqEW",
  consumer_secret: "osGQ364R49cXKeOYSpaOnT++rHs="

For Production:

config :pesapal,
  api_base_url: "https://pay.pesapal.com/v3/api",
  consumer_key: "qkio1BGGYAXTu2JOfm7XSXNruoZsrqEW",
  consumer_secret: "osGQ364R49cXKeOYSpaOnT++rHs="

Link to this section Summary

Functions

authenticate()

Authenticates with Pesapal API and returns an access token.

check_transaction_status(order_tracking_id, token)

Checks the status of a transaction.

initiate_payment(amount, email, currency, ipn_id, callback_url, token, opts \\ [])

Initiates a payment transaction with Pesapal.

register_ipn(webhook_url, token)

Registers an Instant Payment Notification (IPN) webhook with Pesapal.

Link to this section Functions

Link to this function

authenticate()

Authenticates with Pesapal API and returns an access token.

returns

 Returns

  • {:ok, %{"token" => token, "expiryDate" => expiry_date}} - Success with token details
  • {:error, reason} - Error with reason

examples

 Examples 

iex> Pesapal.authenticate("your_key", "your_secret")
{:ok, %{"token" => "abc123", "expiryDate" => "2023-01-01T00:00:00Z"}}
Link to this function

check_transaction_status(order_tracking_id, token)

Checks the status of a transaction.

parameters

 Parameters

  • order_tracking_id - The order tracking ID from initiate_payment/5
  • token - The authentication token from authenticate/2

returns

 Returns

  • {:ok, %{"status" => status, "payment_method" => method, ...}} - Success with transaction details
  • {:error, reason} - Error with reason

examples

 Examples 

iex> Pesapal.check_transaction_status("ord123", "abc123")
{:ok, %{"status" => "COMPLETED", "payment_method" => "MPESA"}}

note

 Note 

The status code represents the payment_status_description.
0 - INVALID
1 - COMPLETED
2 - FAILED
3 - REVERSED
Link to this function

initiate_payment(amount, email, currency, ipn_id, callback_url, token, opts \\ [])

Initiates a payment transaction with Pesapal.

parameters

 Parameters

  • amount - The payment amount (numeric)
  • email - Customer's email address
  • currency - Currency code (e.g., "KES", "USD")
  • ipn_id - IPN ID from register_ipn/2
  • callback_url - Callback URL where customers will be redirected after successful payment
  • token - The authentication token from authenticate/2
  • opts - Optional parameters:
    • :description - Payment description (default: "Payment")
    • :order_id - Custom order ID (default: auto-generated)

returns

 Returns

  • {:ok, %{"order_tracking_id" => id, "redirect_url" => url, ...}} - Success with payment details
  • {:error, reason} - Error with reason

examples

 Examples 

iex> Pesapal.initiate_payment(1000, "user@example.com", "KES", "ipn123", "https://example.com/callback", "abc123")
{:ok, %{"order_tracking_id" => "ord123", "redirect_url" => "https://pesapal.com/payment/..."}}

iex>Pesapal.initiate_payment(1000, "user@example.com", "KES", "ipn123", "https://example.com/callback", "abc123", [description: "Test Payment"])
{:ok, %{"order_tracking_id" => "ord123", "redirect_url" => "https://pesapal.com/payment/..."}}
Link to this function

register_ipn(webhook_url, token)

Registers an Instant Payment Notification (IPN) webhook with Pesapal.

parameters

 Parameters

  • webhook_url - The URL to receive payment notifications
  • token - The authentication token from authenticate/2

returns

 Returns

  • {:ok, %{"ipn_id" => ipn_id, ...}} - Success with IPN details
  • {:error, reason} - Error with reason

examples

 Examples 

iex> Pesapal.register_ipn("https://example.com/webhook", "abc123")
{:ok, %{"ipn_id" => "ipn123", "url" => "https://example.com/webhook"}}