DEV Community: Joy Nyayieka

Integrating Pesapal API 3.0 on Django

Joy Nyayieka — Thu, 11 Sep 2025 09:59:25 +0000

Pesapal is a fintech company that provides secure and convenient digital payment services to individuals and businesses in African countries, including Kenya, Uganda, Tanzania, Malawi, Rwanda, Zambia, and Zimbabwe. I was recently working on a Django project that required integrating the Pesapal API to facilitate seamless transactions within the application. The first step was to review the Pesapal API documentation; however, upon further research, it became unclear how exactly to implement this integration into the project. This article aims to provide a more detailed explanation of how to implement the basic steps specifically within a Django project.

1. Set Up Pesapal Account

Navigate to the Pesapal Developers Portal.
Create a live/production business account.
You will then receive the Consumer Key and Consumer Secret on the registered email.
Ensure your Django project is set up.

2. Install Required Dependencies

Create a requirements.txt file and install the following dependencies:

requests==2.32.4             # HTTP calls to Pesapal API
python-decouple==3.8         # Manage API keys & secrets via .env
djangorestframework==3.16.0  # Build API endpoints for Pesapal integration

3. Configure Environment Variables

Create a .env file in your project root:

# PesaPal Configuration
PESAPAL_CONSUMER_KEY=your_consumer_key_here
PESAPAL_CONSUMER_SECRET=your_consumer_secret_here
PESAPAL_BASE_URL=https://cybqa.pesapal.com/pesapalv3/api/  # Sandbox
# PESAPAL_BASE_URL=https://pay.pesapal.com/pesapalv3/api/  # Production
PESAPAL_IPN_ID=your_ipn_id_here  # Will be generated in Step 7

And to your settings.py:

from decouple import config

# PesaPal Settings
PESAPAL_CONSUMER_KEY = config('PESAPAL_CONSUMER_KEY')
PESAPAL_CONSUMER_SECRET = config('PESAPAL_CONSUMER_SECRET')
PESAPAL_BASE_URL = config('PESAPAL_BASE_URL')
PESAPAL_IPN_ID = config('PESAPAL_IPN_ID', default='')

4. Create `pesapal_service.py` in the Main App

Create the file inside your main app, eg:

Purpose of `pesapal_service.py`

This file is the core integration layer between the Django application layer and the Pesapal API. It contains all the functions required to:

a. Authenticate with Pesapal.

Every request to Pesapal requires an OAuth access token.
This function calls the RequestToken endpoint and returns a token that is valid for a limited time.

def generate_access_token():
    url = f"{BASE_URL}/api/Auth/RequestToken"
    payload = {
        "consumer_key": settings.PESAPAL_CONSUMER_KEY,
        "consumer_secret": settings.PESAPAL_CONSUMER_SECRET
    }
    headers = {
        "Accept": "application/json",
        "Content-Type": "application/json"
    }
    response = requests.post(url, json=payload, headers=headers)
    return response.json().get("token") if response.status_code == 200 else None

b. Registering IPN URL and fetching registered IPNs.

An IPN is an Instant Payment Notification that Pesapal uses to notify your system about payment status changes asynchronously.
The IPN URL is where Pesapal sends asynchronous updates.
Fetching registered IPNs verifies which IPNs are active.

def register_ipn_url(access_token, ipn_url):
    url = f"{BASE_URL}/api/URLSetup/RegisterIPN"
    payload = {
        "url": ipn_url,
        "ipn_notification_type": "GET"
    }
    headers = {
        "Authorization": f"Bearer {access_token}",
        "Accept": "application/json",
        "Content-Type": "application/json"
    }
    return requests.post(url, json=payload, headers=headers)

def get_registered_ipns(access_token):
    url = f"{BASE_URL}/api/URLSetup/GetIpnList"
    headers = {
        "Authorization": f"Bearer {access_token}",
        "Accept": "application/json",
        "Content-Type": "application/json"
    }
    return requests.get(url, headers=headers)

c. Submitting an order.

Sends transaction details to Pesapal, eg, the amount and description, and returns a redirect URL where customers can complete the payment on Pesapal's secure checkout page.

def submit_order_request(access_token, payload):
    url = f"{BASE_URL}/api/Transactions/SubmitOrderRequest"
    headers = {
        "Authorization": f"Bearer {access_token}",
        "Accept": "application/json",
        "Content-Type": "application/json"
    }
    return requests.post(url, json=payload, headers=headers)

d. Checking transaction status.

Important to confirm if a payment was successful before delivering a product or a service.

def get_transaction_status(access_token, tracking_id, merchant_reference):
    url = f"{BASE_URL}/api/Transactions/GetTransactionStatus"
    headers = {
        "Authorization": f"Bearer {access_token}",
        "Accept": "application/json"
    }
    params = {
        "order_tracking_id": tracking_id,
        "order_merchant_reference": merchant_reference
    }
    response = requests.get(url, headers=headers, params=params)

    if response.status_code == 200:
        return response.json().get("payment_status")  # "COMPLETED", "FAILED", etc.
    else:
        return None

It is worth noting that to make the code above production-ready, consider;

Token caching to avoid calling Pesapal for a new token on every request.
Wrap with try/except to ensure error handling.
Add docstrings to functions to ensure a clear description, args, and return values.

After receiving the payment details, store them in the system under the models.py file as in this example;

from django.db import models

class Payment(models.Model):
    order_id = models.CharField(max_length=100)
    amount = models.DecimalField(max_digits=10, decimal_places=2)
    status = models.CharField(max_length=50, default='PENDING')
    tracking_id = models.CharField(max_length=100, null=True, blank=True)
    created_at = models.DateTimeField(auto_now_add=True)

5. Create Payment Views

Here we define Django views that connect the project to the Pesapal service functions. These views are the entry points for the API consumers.

import json
import uuid
from django.http import JsonResponse, HttpResponse
from django.shortcuts import redirect, render
from django.views.decorators.csrf import csrf_exempt

# Import service functions
from .pesapal_service import (
    generate_access_token,
    register_ipn_url,
    get_registered_ipns,
    submit_order_request,
    get_transaction_status,
)


def get_token_view(request):
    """Generate and return a fresh Pesapal OAuth token (for testing/debugging)."""
    token = generate_access_token(force_refresh=True)
    return JsonResponse({"token": token})


def register_ipn_view(request):
    """Register an IPN URL with Pesapal."""
    ipn_url = request.GET.get("url")
    if not ipn_url:
        return JsonResponse({"error": "IPN URL is required"}, status=400)

    res = register_ipn_url(ipn_url)
    return JsonResponse(res)


def list_ipns_view(request):
    """Fetch all registered IPN URLs from Pesapal for verification."""
    res = get_registered_ipns()
    return JsonResponse(res, safe=False)


def create_order_view(request):
    """
    Create a new Pesapal order and return the redirect URL for checkout.
    Payload includes amount, currency, description, callback, IPN, and billing details.
    """
    # Get amount from request body (JSON or form POST)
    if request.content_type == "application/json":
        data = json.loads(request.body)
        amount = float(data.get("amount", 0))
    else:
        amount = float(request.POST.get("amount", 0))

    payload = {
        "id": str(uuid.uuid4()),  # Unique order ID
        "currency": "KES",
        "amount": amount,
        "description": "Payment description goes here",
        "callback_url": "https://yourdomain.com/pesapal/payment-confirm/",
        "notification_id": "YOUR_REGISTERED_IPN_ID",
        "branch": "Store Name - Example",
        "billing_address": {
            "email_address": "customer@example.com",
            "phone_number": "0723xxxxxx",
            "country_code": "KE",
            "first_name": "Juma",
            "last_name": "Mutua",
            "line_1": "Customer Address",
            "city": "Nairobi",
        },
    }

    res = submit_order_request(payload)

    if "redirect_url" in res:
        return JsonResponse({"redirect_url": res["redirect_url"]})
    else:
        return JsonResponse({"error": "Failed to create order"}, status=400)


@csrf_exempt
def ipn_listener(request):
    """
    Update your database with payment status asynchronously.
    """
    tracking_id = request.GET.get("tracking_id")
    merchant_reference = request.GET.get("merchant_reference")

    print(f"[IPN] Tracking ID: {tracking_id}, Reference: {merchant_reference}")
    return HttpResponse("IPN received", status=200)


def payment_confirm(request):
    """
    Callback endpoint: Pesapal redirects the customer here after payment.
    """
    tracking_id = request.GET.get("order_tracking_id")
    merchant_reference = request.GET.get("order_merchant_reference")

    status_response = get_transaction_status(tracking_id, merchant_reference)
    payment_status = status_response.get("payment_status")

    if payment_status == "COMPLETED":
        return redirect("dashboard")  # Example success page
    else:
        return render(request, "payments/payment-failed.html")

The callback_url is the URL where a user of the system is redirected after a successful payment using Pesapal. During development, since the system is not live yet, you can make use of ngrok.

Ngrok is a reverse proxy that enables a developer to expose a local server running on their machine to the internet. This creates a secure tunnel, giving the local server a public URL that can receive webhooks or API callbacks from services like Pesapal. This is crucial because external APIs need a publicly accessible endpoint to send data back to, which they can't do to a local machine's address like http://localhost.

Once you create the endpoint, replace the callback_url with the valid URL. eg
"callback_url": "https://1234-567-890.ngrok-free.app/dashboard". The base URL should also be included in settings.py under the ALLOWED_HOSTS = [...].

6. Configure URLs

Under the Main app's urls.py(specific to this example tutorial), configure the URLs to connect the Pesapal payment views defined.

from django.urls import path
from . import views

urlpatterns = [
    # Utility views
    path("pesapal/token/", views.get_token_view, name="pesapal-get-token"),
    path("pesapal/ipn/register/", views.register_ipn_view, name="pesapal-register-ipn"),
    path("pesapal/ipn/list/", views.list_ipns_view, name="pesapal-list-ipns"),

    # Payment flow
    path("pesapal/order/create/", views.create_order_view, name="pesapal-create-order"),
    path("pesapal/ipn/", views.ipn_listener, name="pesapal-ipn-listener"),
    path("pesapal/payment-confirm/", views.payment_confirm, name="pesapal-payment-confirm"),
]

7. Register IPN URL

Get the IPN ID by running https://yourdomain.com/pesapal/ipn/ and replacing the placeholder in the .env file.

8. Testing

Test the payment flow by checking whether the redirect works, the callback updates the status, and whether the IPN hits the endpoint. When moving to production, switch the API base URL to production and update the keys.

Before production, you might also consider ensuring security, such as using HTTPS, implementing proper error handling for error logging, and configuring a proper domain for callback URLs.

Above are the fundamental steps to integrate the Pesapal API into a Django project. Of course, Pesapal has many other services like handling recurring payments, refund request and order cancellation that are not included in the article but are equally useful (documentation).

I hope you have found this useful! I'd be happy to get your feedback on it. See you in the next one. 🫡

Python Built-in Data Structures(II)

Joy Nyayieka — Tue, 13 May 2025 10:23:35 +0000

This second article picks up where we left off, moving from lists and tuples to sets and dictionaries. By the end of this article, we should get a resounding answer to my Python instructor's question.

Sets

my_set = {1, 2, (4, 5)}

A set is a collection of unique data; therefore, no element within a set can be duplicated, eg, True and 1 or False and 0.

They are useful in membership testing because they use a hash table under the hood, and to eliminate duplicate entries, eg, storing information about student IDs.

Set objects also support mathematical operations like union, intersection, difference, and symmetric difference.

Key Features of a Set

Unordered - elements cannot be accessed in a specific order
Mutable - elements can be altered after creation.
No duplicates - elements are all unique.
Unindexed - items cannot be accessed via indexes.

Common Set Methods

Method	Description
`add()`	Adds an element to the set.
`discard()`	Removes an element if present.
`clear()`	Removes all elements.
`copy()`	Returns a shallow copy.
`union()`	Returns the set containing the union of sets.
`intersection()`	Returns a set that is the intersection of two other sets.
`difference()`	Returns a set containing the difference between two or more sets.
`symmetric_difference()`	Returns elements that are in either of the two sets but not in both.

Similar to list comprehensions, set comprehensions are also supported.

evens = {x for x in range(11) if x % 2 == 0}
print(evens)

Output
{0, 2, 4, 6, 8, 10}

When to use Sets

When carrying out mathematical set operations upon the data, like union or intersection.
Membership testing - checking if an element exists within a set, which is faster than using a list or tuple.
Removing duplicates - sets remove duplicates that can be useful in finding the unique count of items.
Efficient lookups - as a result of the fast membership testing, sets are useful when checking if an item is present in a collection.

Dictionaries

phonebook = {'Ali': 0712345, 'Maria': 0721435}

A dictionary stores values in key-value pairs. Similar to real-world dictionaries, each word(key) has a definition(value), requiring the keys to be unique within one dictionary.

Key Features of a Dictionary

Ordered - as of Python version 3.7
Keys are case sensitive.
Keys must be unique - duplicate keys are not allowed
Internally uses hashing - operations can be performed in constant time.
Mutable - items can be changed, added or removed after the dictionary has been created.

Common Dictionary Methods

Method	Description
`pop()`	Removes the item with the specified key.
`clear()`	Removes all items from the dictionary.
`keys()`	Returns all the dictionary's keys.
`values()`	Returns all the dictionary's values.
`items()`	Returns a view object that displays a list of dictionary's key-value tuple pairs.
`get()`	Returns the value of the specified key.
`popitem()`	Removes and returns the last key-value pair.

When to use a Dictionary

Fast lookups by unique key. For example, looking up a person's phone number using their name in a contact list.
When working with data that has a clear mapping. eg, mapping user IDs to the user info.
When organizing structured data. eg, storing a person's profile with fields like name, age and email.
When grouping related information together. eg, storing the country name and the capital city.

Comparison of Python Data Structures

Type	Mutable	Ordered	Indexed	Allows Duplicates	Key-Value Pairs	Use Case Example
`list`	✅	✅	✅	✅	❌	Storing a sequence of items (e.g., tasks)
`tuple`	❌	✅	✅	✅	❌	Fixed data (e.g., coordinates, RGB values)
`set`	✅	❌	❌	❌	❌	Unique items collection (e.g., tags)
`dict`	✅	✅*	❌	✅ (keys: ❌)	✅	Key-value mapping (e.g., user profiles)

In conclusion, sets are mutable, not '-utable'.

Python Built-in Data Structures(I)

Joy Nyayieka — Sun, 11 May 2025 20:21:14 +0000

Recently, a Python instructor asked me whether a set is mutable or immutable. I can't clearly remember what I said, but I did get the last part of the words correct because I remember saying '-utable', which reminded me of the viral video of the backbenchers in a class answering that the pressure 'creases' instead of a comprehensive 'increases' or 'decreases'. This led me to researching the built-in data structures in Python, and below is the first part of the summary of my findings.

Lists

fruits = ["banana", "mango", "watermelon"]

Lists are used to store multiple items in a single variable. They can be defined using square brackets [ ] or the list type function

Key Features of Lists

Ordered - maintain the order of elements.
Mutable - items can be modified after creation.
Heterogeneous - elements can be of different data types.
Allow duplicates - can contain duplicate values.
Indexed - accessing items can be done directly using their index, starting from 0.

It is important to note that lists store references rather than values. Elements in a list are not stored directly in the list structure; rather, the list stores pointers to the actual objects in memory.

Common List Operations

Method	Description
`count(x)`	Returns the number of times x appears in the list
`append(x)`	Adds x to the end of the list
`insert(i,x)`	Inserts x at index i
`remove(x)`	Remove the first item with the value x
`pop([i])`	Remove item at position i and return it
`clear()`	Removes all items from the list
`reverse()`	Reverse the elements of the list in place
`index(x)`	Returns the index of the first value of x
`sort()`	Lists in ascending or descending order
`copy()`	Returns the shallow copy of the list

List Comprehensions

List comprehensions provide a concise way of creating new lists based on the values of an existing list.
For example, we have a list of numbers and we want to generate the square of each element in the list.

numbers = [1, 2, 3, 4]

#List comprehension to create a new list
squared_numbers = [num** 2 for num in numbers]

print(squared_numbers)

Output
[1, 4, 9, 16]

When to use Lists

Storing collections of related items. For example, a program that tracks student names in a classroom would use a list like students = ["Njoroge", "Karen", "Fatuma", "Chebet", "Juma"] to maintain all names in one organized structure.
Iterating through sequential data. For example, when sending email notifications to multiple recipients, a program would loop through a list of email addresses to send the same message to each person.
Temporary storage of results. For example, when scraping a website, a program accumulates all URLs in a list before processing them further or saving them to a database.
Lists allow programmers to create new data collections by transforming or filtering existing data. For example, automatically create a new list with just the scores above 70 for a list of test scores.

Tuples

my_tuple = ("Alice", 15, "Student")

Tuples, like lists, store multiple items in a single variable. The primary difference, however, is that tuples cannot be changed after their creation.

Key Features of Tuples

Ordered - elements are in a specific sequence.
Immutable - cannot be changed after their creation.
Defined using parentheses().
Allow duplicates.
Heterogeneous - can contain mixed data types.

Common Tuple Operations

Due to the immutability of tuples, there are only two tuple methods that a tuple object can call.

Method	Description
`count(x)`	Returns the number of times `x` appears in tuple
`index(x)`	Returns the index of the first occurrence of `x`

When to use Tuples

For efficient looping - useful for looping over fixed data like days of the week in a calendar app.
Packing/unpacking values - for example, when processing student records, like extracting name and grade from a database tuple.
Immutable records - good for creating read-only data structures like coordinates or database rows.
Dictionary keys - tuples of coordinates (latitude, longitude) can be used as dictionary keys to store location details, ensuring consistency and suitability for lookup operations.

As mentioned before, the fundamental difference between lists and tuples is that lists are mutable while tuples are not. As a result, list object provide more methods but at the cost of memory space. Take the example below:

import sys
a_list = ['Maina', 'Football', 1, 3.142, True]
a_tuple = ('Chebet', 'Tennis', 2, 13.31, False)
print('The list size:', sys.getsizeof(a_list), 'bytes')
print('The tuple size:', sys.getsizeof(a_tuple), 'bytes')

Outputs
The list size: 104 bytes The tuple size: 80 bytes

This difference becomes more apparent when working with big data. Immutability makes notable optimization as well as making processing much faster, which is efficient when working with millions of sequence objects.

Thus far, can you explain when to use a list over a tuple and vice versa? And more importantly, for the people at the back, are tuples mutable or immutable?

Introduction to Data Analysis using Microsoft Excel

Joy Nyayieka — Wed, 30 Apr 2025 08:55:06 +0000

Presently, more and more businesses are utilizing data to make decisions as opposed to using strategies like their intuition or speculation. This has been a result of the rise of big data, with companies like Facebook having about 3.06 billion active users every month.

When aptly analysed, such data is highly beneficial not only to business owners who optimize their businesses but also to users who get more personalized experiences, among other advantages. Consequently, any new data analyst must select a powerful tool that has a fairly gentle learning curve to analyze complex datasets. Microsoft Excel is one such tool that fits this description and is used by most data analysts.

Useful Data Analysis Features in Excel

Formulas and Functions
Sorting and Filtering Data
Logical Functions
Conditional Formatting and Data Validation
Excel Tables
Charts and Graphics
PivotTables and PivotCharts
Data Cleaning

Formulas and Functions

Always starts with an equal sign, a formula is an expression that is used for calculation on data in a worksheet.

Example: =A1+A2

A function, on the other hand, is a predefined formula that simplifies complex calculations.

Examples:

=SUM(A1:A10)- Calculates the summation

=AVERAGE(B1:B5)- Calculates the mean

Sorting and Filtering Data

Sorting arranges the data into a meaningful order, either in ascending or descending order.

Filtered data displays only the rows that meet the criteria that you specify and hides rows that you do not want displayed.

In Excel, under the Home tab, select Sort & Filter to display the sorting options available and the filter option.

For example, a data analyst has a list of customer orders with columns for “Product” and “Price.” To find the most expensive orders for a specific product, they would first filter the “Product” column to show only the desired item and then sort the “Price” column in descending order.

Logical Functions

Excel offers 4 logical functions, ie, AND, OR, XOR, and NOT. These functions are useful when making more than one comparison or testing multiple conditions instead of a single one.

AND- returns true if both arguments satisfy the condition

eg. =AND(A1>10,A2<30): the formula returns TRUE if the value in cell A1 is greater than 10 and the value in A2 is less than 30, FALSE otherwise.

OR- returns TRUE if at least one argument is true

eg. =OR(A1>=10, B1<10): returns TRUE if A1 is greater than or equal to 10 or B1 is less than 10 or both. If A1 is less than 10 and B1 is greater than 10, then the formula returns FALSE.

XOR- returns a logical exclusive Or of all arguments

eg. =XOR(A1>=10, A2<10): returns TRUE if one of either A1 is greater or equal to 10 or A2 is less than 10, returns FALSE otherwise.

NOT- negates the logical value of its argument

eg. =NOT(A1>10): returns FALSE if the value in A1 is greater than 10, TRUE otherwise.

In addition to the above logical functions, Excel provides conditional functions, ie, IF, IFS, and SWITCH, that are used to make a decision based on a condition.

Conditional Formatting and Data Validation

Nested under the Home tab, Conditional formatting is a useful feature to help analysts visually emphasize data and identify trends. For example, to find out the products that generated the highest and lowest revenue, a data analyst would select the “Revenue” column and apply conditional formatting. This highlights top-performing products and underperforming ones in a different colour.

Data Validation is an equally important feature as it restricts the type of data that can be entered into a cell. For example to data validation rules can be applied to the “Age” column to prevent illogical entries like negative numbers or extremely large numbers.

Excel Tables

Using tables offers advantages such as automatic formatting and filtering, structured referencing, range expansion, and better readability.

To convert data to a table:

Click the Insert tab after selecting the data range
Select Table and tick “My table has headers”
Click OK.

Charts and Graphics

Charts help to visually present data in different forms depending on the variables being represented. When selecting a chart to represent your data, it is important to evaluate which chart would best tell the data story.

Some of the charts in Excel include:

Column chart- compares totals of different categories over time
Bar chart- compares categories with long labels
Line chart- shows trends over time
Pie chart- shows part of the whole
Area chart- visualizes cumulative changes of multiple variables over time
Scatter chart- visualizes the relationship between 2 numerical values

Frequently used in dashboards, these charts are easily generated by selecting the data range and selecting the specific chart needed under the Insert tab.

Additionally, sparklines are bars that are embedded into a single cell that visualize data trends. Similarly, data bars are a type of conditional formatting that adds colour to cells in a range to indicate how large the cell values are compared to the other values.

PivotTables and PivotCharts

PivotTables are a functionality that helps an analyst group and summarize large data sets. One can add or remove values, perform calculations, and filter and sort data sets.

For example, when working with a large dataset with numerous columns and rows of numerical data, such as traffic data and user demographics. Pivot tables enable the analyst to perform calculations that properly summarize this information, like finding the sums and counts. This enables efficient data analysis, like answering questions like the amount of total website traffic for different categories of users in a certain month.

In Excel, select the data range and click PivotTable under the Insert tab. Drag variables into either the Rows or Values, depending on the insight being sort. Adding slicers to the PivotChart adds more interactivity to the visualization.

Data Cleaning

It is no secret that the quality of the output of an analyst’s visualization greatly depends on how thoroughly data is preprocessed. With data cleaning being one of the major steps of data preprocessing, it is paramount that great effort is put into ensuring that the dataset is as optimal for use as it can be.

Some of the cleaning techniques used in Excel include:

Removing duplicate rows
Handling missing values- this can be done by filling a specific value like 0 or filling in the mean(=AVERAGE(A:A) among others.
Standardizing text eg =LOWER(A1), =UPPER(A1), =TRIM(A1) etc.
Combining columns eg, combining first name and last name, =A1& “ ”&B1
Converting the data type eg, numeric fields mistakenly stored as text
Using the Find and Replace feature

Mentioned above are the basic features that an individual who is new to data analysis would find useful in Microsoft Excel. Although not an exhaustive list, it suffices to nudge you in the right direction.