Banking Tech

PesaPal Integration Guide: Accept Payments on Your Website

E-commerce retailers, SaaS application providers, digital media platforms, and educational institutions operating in Uganda and across East Africa require payment processing solutions capable of accepting diverse payment options through a single, unified checkout experience. PesaPal is a leading payment aggregator in the region, enabling merchants across Uganda, Kenya, Tanzania, and Rwanda to accept Visa, Mastercard, American Express, MTN Mobile Money, and Airtel Money seamlessly. This complete developer integration guide demonstrates how to implement the PesaPal V3 REST API into your web application to accept online payments securely.

Architecture Overview of PesaPal V3 REST API

The PesaPal V3 API is built on a modern RESTful architecture utilizing JSON payloads and OAuth 2.0 authentication. A complete payment transaction integration follows five structured engineering steps:

1. Merchant Authentication: Exchange your merchant Consumer Key and Consumer Secret for a short-lived OAuth Bearer Token.
2. IPN Listener Registration: Register a Instant Payment Notification (IPN) webhook URL on your server where PesaPal posts real-time payment status updates.
3. Order Request Submission: Post order details (amount, currency, customer info) to PesaPal to generate an order tracking ID and payment iframe URL.
4. User Payment Execution: Redirect the customer to PesaPal's hosted payment gateway page where they select their preferred payment channel (Card or Mobile Money).
5. IPN Verification & Order Fulfillment: Handle incoming PesaPal IPN webhooks on your server and execute server-to-server status queries before fulfilling customer orders.

Step 1: Merchant Authentication and Token Generation

First, retrieve your Consumer Key and Consumer Secret from your PesaPal Merchant Dashboard. Request an OAuth access token by issuing an HTTP POST request to the authentication endpoint:

Endpoint (Sandbox): POST https://cyb3rwr34k.pesapal.com/api/Auth/RequestToken
Endpoint (Production): POST https://pay.pesapal.com/v3/api/Auth/RequestToken

Request JSON Payload

{
  "consumer_key": "YOUR_CONSUMER_KEY",
  "consumer_secret": "YOUR_CONSUMER_SECRET"
}

The API responds with an OAuth token string valid for 5 minutes. Implement automated caching logic on your web server to refresh tokens as needed during user checkout sessions.

Step 2: Registering Your IPN Webhook Listener

PesaPal notifies your server when transactions are processed via Instant Payment Notifications (IPN). You must register your webhook listener URL before submitting customer orders:

Endpoint: POST /api/URLSetup/RegisterIPN
Headers: Authorization: Bearer {token}

Request JSON Body

{
  "url": "https://yourdomain.com/api/pesapal-ipn",
  "ipn_notification_type": "POST"
}

PesaPal returns a unique ipn_id string. Store this ipn_id in your application's environment configuration, as it must be attached to every subsequent order submission payload.

Step 3: Submitting an Order and Rendering Checkout

When a customer clicks the checkout button on your web application, submit the order details to PesaPal's order submission endpoint:

Endpoint: POST /api/Transactions/SubmitOrderRequest
Headers: Authorization: Bearer {token}

Order Submission Payload Example

{
  "id": "ORD-UG-2026-8812",
  "currency": "UGX",
  "amount": 150000,
  "description": "Payment for Software License",
  "callback_url": "https://yourdomain.com/checkout/success",
  "notification_id": "YOUR_REGISTERED_IPN_ID",
  "billing_address": {
    "email_address": "buyer@example.com",
    "phone_number": "256782000111",
    "first_name": "Derick",
    "last_name": "Asiimwe",
    "line_1": "Kampala Road",
    "city": "Kampala",
    "country_code": "UG"
  }
}

The response contains an order_tracking_id and a redirect_url. Redirect the user's browser window to this URL to display the secure payment interface where they can select Card or Mobile Money.

Step 4: Handling IPN Notifications & Verifying Status

Upon payment completion or cancellation, PesaPal issues a POST request to your registered IPN URL containing the OrderTrackingId and OrderNotificationType.

Always execute a server-to-server status query to verify transaction integrity before updating order status in your database:

• Issue a GET request to /api/Transactions/GetTransactionStatus?orderTrackingId={OrderTrackingId}.
• Verify that the status field equals COMPLETED. Other possible states include FAILED or REVERSED.
• When status equals COMPLETED, mark the invoice as paid in your database, emit customer receipts, and respond to PesaPal with an HTTP 200 OK JSON payload.

Best Practices for East African E-Commerce Platforms

• Multi-Currency Pricing Support: Display prices in local currency (UGX, KES) for East African buyers while offering USD billing for international clients.
• Cart Abandonment Follow-up: Save pending transaction draft records in your database prior to gateway redirect so customer support can assist failed sessions.
• Security and SSL Encryption: Enforce HTTPS TLS 1.3 across all payment endpoints and validate transaction amounts server-side to prevent payload manipulation.

Build Custom E-Commerce Solutions with DeryCode Tech

Integrating online payment gateways demands robust software engineering to eliminate dropped orders, transaction double-counting, and security vulnerabilities. DeryCode Tech, founded by technology leader Asiimwe Derick in Kampala, Uganda, builds enterprise e-commerce web applications, SaaS platforms, and custom payment middleware across East Africa.

Need expert developers to integrate PesaPal, card gateways, or mobile money payments into your app? Get in touch with DeryCode Tech today for world-class development services.