Coder Legion - Recent posts tagged pawapay

The Easiest Way to Integrate pawaPay in Your Java Spring Boot App

Mon, 01 Jun 2026 10:08:14 +0000

Building a high-throughput mobile money gateway is often romanticized as a simple REST API integration. The reality, however, is a brutal landscape of undocumented MNO network drops, complex cryptographic signature requirements, and terrifying double-spend vulnerabilities. When development teams attempt to hand-roll these integrations using standard Java HTTP clients like OkHttp or RestTemplate, they inadvertently construct a fragile house of cards. They pull highly sensitive environment secrets directly into the JVM heap to manually compute Signature-Input headers, exposing their financial infrastructure to memory scraping and reverse-engineering. Furthermore, relying on blocking I/O to wait for unpredictable African telecom networks guarantees that thread pools will eventually exhaust, triggering cascading outages across the entire application architecture.

This is the integration illusion. You think you are building a simple payment gateway, but you are actually attempting to build a secure, fault-tolerant, state-managing cryptographic vault from scratch.

We recognized that engineering teams do not have months to waste debugging manual boilerplate. You need speed, concurrency, and ironclad security from day one. To solve this, we engineered the pawaPay Java SDK—a completely new paradigm for mobile money integration that shifts the heavy lifting away from your application logic and into a compiled, memory-safe environment. By adopting this architecture, you can execute non-blocking, asynchronous mobile money deposits and payouts in under five minutes.

Step One: Securing the Artifact

The foundation of a secure integration begins with your dependency management. We distribute the official package directly through Maven Central, ensuring you receive cryptographically verified, unaltered binaries. You can view the live artifact registry at https://central.sonatype.com/artifact/com.katorymnd/pawapay-java-sdk to verify the latest release versions.

To bring the native power of the SDK into your project, simply declare it within your pom.xml configuration file.

<dependency>
    <groupId>com.katorymnd</groupId>
    <artifactId>pawapay-java-sdk</artifactId>
    <version>LATEST_VERSION</version>
</dependency>

Once synced, you are no longer just importing a library; you are embedding a highly optimized Java Native Interface (JNI) vault engineered in Rust. This core will handle all payload serialization and cryptographic signing entirely outside of the standard Java memory space, neutralizing standard de-compilation threats immediately.

Step Two: Zero-Trust Configuration

We engineer under the assumption that application state can be volatile, which is why we enforce a strict, zero-trust initialization process. There are no fallback secrets, and there are no dummy variables allowed. Your master API tokens and your specific Katorymnd license key must be injected via strict environment variables. If these are missing or malformed, the SDK aborts the boot sequence instantly to protect your system from executing unauthenticated requests.

To wire this into a Spring Boot application, you construct a dedicated @Configuration class. This class uses our Config.Builder to construct the environment parameters and boot the ApiClient securely.

import com.katorymnd.pawapay.sdk.api.ApiClient;
import com.katorymnd.pawapay.sdk.config.Config;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class PawaPayGatewayConfig {

    @Bean
    public ApiClient pawaPayClient() {
        String apiKey = System.getenv("PAWAPAY_API_TOKEN");
        String licenseKey = System.getenv("KATORYMND_PAWAPAY_SDK_LICENSE_KEY");

        Config config = new Config.Builder()
            .apiKey(apiKey)
            .environment("production")
            .timeout(30000)
            .build();

        return new ApiClient(config, licenseKey, true, "v2");
    }
}

By defining the ApiClient as a Spring Bean, you ensure the native vault is loaded exactly once during the application lifecycle. The vault establishes the secure connection pool, locks in the hardware anchoring, and remains resident in memory, ready to process thousands of concurrent requests without the overhead of re-initialization.

Step Three: The Reactive Endpoint

The true architectural elegance of this integration reveals itself at the routing layer. Because the SDK was built specifically for modern, high-throughput environments, every core method returns a CompletableFuture. This maps natively to Project Reactor, allowing you to build completely non-blocking Spring WebFlux endpoints.

When a payload arrives, your application threads do not wait. The request is handed to the native core, and the thread is immediately liberated back to the pool to handle other users.

import com.katorymnd.pawapay.sdk.api.ApiClient;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.reactive.function.server.RouterFunction;
import org.springframework.web.reactive.function.server.ServerResponse;
import reactor.core.publisher.Mono;

import java.util.Map;

import static org.springframework.web.reactive.function.server.RequestPredicates.POST;
import static org.springframework.web.reactive.function.server.RouterFunctions.route;

@Configuration
public class DepositController {

    @Bean
    public RouterFunction<ServerResponse> handleDeposit(ApiClient pawaPayClient) {
        return route(POST("/api/v2/payments/deposit"), request -> 
            request.bodyToMono(Map.class)
                .flatMap(payload -> Mono.fromFuture(
                    pawaPayClient.initiateDepositV2(
                        payload.get("transactionId").toString(),
                        payload.get("amount").toString(),
                        payload.get("currency").toString(),
                        payload.get("phone").toString(),
                        payload.get("provider").toString(),
                        "Spring WebFlux Integration",
                        null, null, null
                    )
                ))
                .flatMap(response -> ServerResponse.ok().bodyValue(response))
                .onErrorResume(error -> ServerResponse.badRequest().bodyValue(Map.of("error", error.getMessage())))
        );
    }
}

In just three steps, you have bypassed weeks of manual REST implementation. You possess an endpoint that can absorb massive MNO latency spikes without crashing your server, backed by a cryptographic engine that mathematically guarantees your payload integrity.

Validating the Architecture

Before writing a single line of your own code, you can visually verify this exact execution flow. We have exposed our internal, Javalin-based disposable execution environment to the public. By visiting the live playground at https://katorymnd.dev/pawapay-demo/java/, you can input your sandbox tokens and watch the native core process deposits, handle automated config syncs, and securely fetch MNO availability in real-time. It provides a transparent, terminal-level view of the exact security validations happening beneath the surface of the SDK.

Transitioning to Enterprise Production

While the artifact is freely available on Maven Central for integration testing, deploying this architecture into a live financial environment requires absolute operational certainty. For businesses processing real capital, we offer the Premium License infrastructure detailed at https://katorymnd.com/pawapay-payment-sdk/java.

Securing a premium license unlocks critical production features, including custom domain locking to prevent your API keys from being used outside of authorized IP addresses, emergency technical support SLAs, and architectural consultation for your specific database synchronization strategy. It is the definitive path for teams that refuse to compromise on gateway resilience.

Stop wrestling with clunky HTTP clients and vulnerable cryptographic libraries. Cut the boilerplate, implement the native SDK, and secure your mobile money infrastructure today.

pawaPay PHP SDK v4.4.0 adds dual V1/V2 support

Tue, 12 Aug 2025 19:24:36 +0000

pawaPay PHP SDK v4.4.0, Dual Version Support [V1 + V2], Seamless Migration

pawaPay helps teams accept and move money across African markets with a clean API surface. In v4.4.0 of the pawaPay PHP SDK, we introduced dual version support so V1 and V2 can live together in one codebase. Think of it as two gears turning in sync, V1 for stability, V2 for velocity.

This design gives you the freedom to adopt V2 where it shines, while keeping proven V1 flows earning in production.

Why dual version support
What changed in v4.4.0
Environment setup and configuration
Full runnable examples, V1 and V2
Hosted Payment Page, end to end
Verification flow, returnUrl and verify without cURL
Testing and safety nets with PHPUnit
Migration playbook, step by step
Edge cases, country notes, and logging
Troubleshooting guide
Security notes and hardening tips
Where to get it

1) Why dual version support

Upgrading payments is risky. Teams struggle with three realities:

All or nothing switches increase outage risk.
Two SDKs mean duplicate configs and twice the drift.
Testing in production is scary without a clean rollback.

Our approach: keep V1 as the default, allow V2 to be toggled by environment or per call. You get gradual rollouts, quick comparisons, and instant fallback.

2) What changed in v4.4.0

Version aware client. Pass v1 or v2.
Hosted Payment Page usable from both versions.
Split config files for clarity: active_conf_v1.json, active_conf_v2.json, plus versioned MNO availability JSONs.
Better failure mapping via an improved FailureCodeHelper.
Cleaner errors that mention the version expectation.

3) Environment setup and configuration

Create a .env with clear tokens per environment.

# .env
ENVIRONMENT=sandbox
PAWAPAY_SANDBOX_API_TOKEN=your_sandbox_api_token_here
PAWAPAY_PRODUCTION_API_TOKEN=your_production_api_token_here

# Choose default API version across your app
PAWAPAY_API_VERSION=v1

Composer install:

composer require katorymnd/pawa-pay-integration

4) Full runnable examples, V1 and V2

A) Minimal V1 example, server side initiation

<?php
/**
 * Example: Minimal V1 deposit initiation
 * Goal, show a working flow with V1 as default.
 * Notes, reads ENV, builds a V1 client, initiates a classic deposit call.
 */

require_once __DIR__ . '/../vendor/autoload.php';

use Dotenv\Dotenv;
use Katorymnd\PawaPayIntegration\Api\ApiClient;

$dotenv = Dotenv::createImmutable(__DIR__ . '/..');
$dotenv->load();

$environment = getenv('ENVIRONMENT') ?: 'sandbox';
$sslVerify   = ($environment === 'production');
$apiTokenKey = 'PAWAPAY_' . strtoupper($environment) . '_API_TOKEN';
$apiToken    = $_ENV[$apiTokenKey] ?? null;

if (!$apiToken) {
    http_response_code(500);
    echo 'Missing API token';
    exit;
}

$client = new ApiClient($apiToken, $environment, $sslVerify, 'v1');

// Payload shape may differ per version, keep V1 fields here
$resp = $client->initiateDeposit([
    'amount'      => '15000',
    'currency'    => 'UGX',
    'phoneNumber' => '256753456789',
    'mno'         => 'MTN',
    'reason'      => 'Order #1234',
]);

header('Content-Type: application/json');
echo json_encode($resp, JSON_PRETTY_PRINT);

B) Minimal V2 example, auto flow

<?php
/**
 * Example: Minimal V2 deposit initiation (auto)
 * Goal, exercise the new V2 route without touching V1 code.
 * Notes, just switch the version to v2.
 */

require_once __DIR__ . '/../vendor/autoload.php';

use Dotenv\Dotenv;
use Katorymnd\PawaPayIntegration\Api\ApiClient;

$dotenv = Dotenv::createImmutable(__DIR__ . '/..');
$dotenv->load();

$environment = getenv('ENVIRONMENT') ?: 'sandbox';
$sslVerify   = ($environment === 'production');
$apiTokenKey = 'PAWAPAY_' . strtoupper($environment) . '_API_TOKEN';
$apiToken    = $_ENV[$apiTokenKey] ?? null;

if (!$apiToken) {
    http_response_code(500);
    echo 'Missing API token';
    exit;
}

$client = new ApiClient($apiToken, $environment, $sslVerify, 'v2');

// V2 supports initiateDepositAuto which may return a redirect, or a ready status
$resp = $client->initiateDepositAuto([
    'amount'      => '15000',
    'currency'    => 'UGX',
    'phoneNumber' => '256753456789',
    'mno'         => 'MTN',
    'returnUrl'   => 'https://example.com/paymentProcessed',
]);

header('Content-Type: application/json');
echo json_encode($resp, JSON_PRETTY_PRINT);

Why both examples matter
You can test V2 side by side, compare payloads and responses, and fall back to V1 with a single parameter change.

5) Hosted Payment Page, end to end

The hosted page is the fastest way to collect a payment with one redirect.

<?php
/**
 * Example: Hosted Payment Page, works with V1 or V2
 * Goal, show a clean redirect based on initiateDepositAuto.
 */

require_once __DIR__ . '/../vendor/autoload.php';

use Dotenv\Dotenv;
use Monolog\Logger;
use Monolog\Handler\StreamHandler;
use Katorymnd\PawaPayIntegration\Api\ApiClient;
use Katorymnd\PawaPayIntegration\Utils\Helpers;

$dotenv = Dotenv::createImmutable(__DIR__ . '/..');
$dotenv->load();

$environment = getenv('ENVIRONMENT') ?: 'sandbox';
$sslVerify   = ($environment === 'production');
$apiVersion  = getenv('PAWAPAY_API_VERSION') ?: 'v1';
$apiTokenKey = 'PAWAPAY_' . strtoupper($environment) . '_API_TOKEN';
$apiToken    = $_ENV[$apiTokenKey] ?? null;

if (!$apiToken) {
    http_response_code(500);
    echo 'Missing API token';
    exit;
}

$log = new Logger('pawaPay');
$log->pushHandler(new StreamHandler(__DIR__ . '/../logs/payment_success.log', \Monolog\Level::Info));
$log->pushHandler(new StreamHandler(__DIR__ . '/../logs/payment_failed.log',  \Monolog\Level::Error));

$client = new ApiClient($apiToken, $environment, $sslVerify, $apiVersion);

// Inputs, in real apps take these from your form
$depositId            = Helpers::generateUniqueId();
$amount               = '15000';
$currency             = 'UGX';
$msisdn               = '256753456789';
$mno                  = 'MTN';
$returnUrl            = 'https://your-app.example/returnUrl.php';
$statementDescription = 'Order 1234';

// V2 will typically return a redirect URL for the hosted page
try {
    $resp = $client->initiateDepositAuto([
        'amount'      => $amount,
        'currency'    => $currency,
        'phoneNumber' => $msisdn,
        'mno'         => $mno,
        'returnUrl'   => $returnUrl,
        'reason'      => $statementDescription,
        'metadata'    => ['depositId' => $depositId],
    ]);

    if (!empty($resp['redirectUrl'])) {
        header('Location: ' . $resp['redirectUrl']);
        exit;
    }

    // If no redirect is required, log and show the result
    $log->info('Hosted page not required', ['resp' => $resp]);
    header('Content-Type: application/json');
    echo json_encode($resp, JSON_PRETTY_PRINT);
} catch (\Throwable $e) {
    $log->error('Hosted page error', ['ex' => $e->getMessage()]);
    http_response_code(500);
    echo 'Payment initiation failed';
}

6) Verification flow, returnUrl and verify without cURL

Many teams prefer not to make HTTP calls to a sibling script. You can include the verifier directly.

verify.php

<?php
/**
 * verify.php
 * Purpose, encapsulate verification logic that can be included from returnUrl.php
 * Input, expects $client and $transactionId to be in scope when included
 * Output, returns associative array $verification
 */

if (!isset($client) || !isset($transactionId)) {
    throw new \RuntimeException('verify.php expects $client and $transactionId');
}

$verification = $client->checkTransactionStatus([
    'transactionId' => $transactionId,
]);

// The parent script will read $verification

returnUrl.php

<?php
/**
 * returnUrl.php
 * Purpose, handle redirected users after payment, then verify internally
 */

require_once __DIR__ . '/../vendor/autoload.php';

use Dotenv\Dotenv;
use Katorymnd\PawaPayIntegration\Api\ApiClient;

$dotenv = Dotenv::createImmutable(__DIR__ . '/..');
$dotenv->load();

$environment = getenv('ENVIRONMENT') ?: 'sandbox';
$sslVerify   = ($environment === 'production');
$apiVersion  = getenv('PAWAPAY_API_VERSION') ?: 'v2';
$apiTokenKey = 'PAWAPAY_' . strtoupper($environment) . '_API_TOKEN';
$apiToken    = $_ENV[$apiTokenKey] ?? null;

$client = new ApiClient($apiToken, $environment, $sslVerify, $apiVersion);

// Transaction id from provider redirect or your metadata
$transactionId = $_GET['txId'] ?? $_POST['txId'] ?? null;

if (!$transactionId) {
    http_response_code(400);
    echo 'Missing transactionId';
    exit;
}

// Include verifier in-process, no cURL required
$verification = [];
require __DIR__ . '/verify.php';

// Persist result, show receipt, or redirect to success page
header('Content-Type: application/json');
echo json_encode(['verified' => true, 'result' => $verification], JSON_PRETTY_PRINT);

Why this is safe and simple
You keep the verification logic pure PHP, no extra HTTP hops, fewer moving parts, clearer stack traces.

7) Testing and safety nets with PHPUnit

A tiny guard to ensure your app respects the chosen version.

<?php
/**
 * tests/VersionSelectionTest.php
 * Purpose, assert the client honors PAWAPAY_API_VERSION, prevent regressions.
 */

use PHPUnit\Framework\TestCase;
use Katorymnd\PawaPayIntegration\Api\ApiClient;

final class VersionSelectionTest extends TestCase
{
    public function testChoosesV2WhenEnvSaysV2(): void
    {
        $client = new ApiClient('fake', 'sandbox', false, 'v2');
        $this->assertTrue(method_exists($client, 'initiateDepositAuto'), 'V2 method should exist');
    }

    public function testChoosesV1WhenEnvSaysV1(): void
    {
        $client = new ApiClient('fake', 'sandbox', false, 'v1');
        $this->assertTrue(method_exists($client, 'initiateDeposit'), 'V1 method should exist');
    }
}

Add more tests for response shape, error handling, and idempotency.

8) Migration playbook, step by step

Inventory your live flows, deposit, payout, refund, reconciliation.
Enable dual version globally with PAWAPAY_API_VERSION=v1.
Stand up V2 in sandbox, run the minimal V2 example.
Mirror payloads and compare responses, store both logs.
Dark launch V2 for a small traffic slice, or specific markets.
Monitor failure codes with FailureCodeHelper, alert on deltas.
Flip a single product line to V2, observe for one full billing cycle.
Rollback rule documented, set the env back to v1 if anything spikes.
Expand V2 to more flows after two stable weeks.
Retire V1 only when every flow is stable in V2.

Alternative to env flags
Use a feature flag service or a per request switch. Env is simple, flags give you finer control per tenant, market, or route.

9) Edge cases, country notes, and logging

MNO requirements differ. Some providers are strict on MSISDN formatting, always sanitize to digits and include country code.
Currencies vary. Lock your currency per market in config, do not trust form inputs.
Retrials. Use idempotent keys where available, or your own depositId.
Logs by version. Write to payment_v1.log and payment_v2.log so comparisons are easy.
Metadata discipline. Pass your order or cart reference to simplify reconciliation.

10) Troubleshooting guide

Missing API token, check .env names and ENVIRONMENT.
Method not found when calling V2, confirm you constructed the client with v2.
Unexpected currency error, confirm ISO code and market pairing.
Callback not firing, verify your returnUrl is public and uses HTTPS in production.
Random declines, try a different MNO in sandbox, then compare failure codes with FailureCodeHelper.

11) Security notes and hardening tips

Keep tokens outside your repo, use .env and secret managers.
Verify all incoming callbacks, do not rely only on query params, call checkTransactionStatus.
Store only what you need, mask MSISDN in logs, rotate tokens on schedule.
Enforce TLS, set sslVerify=true in production.

12) Where to get it

GitHub, https://github.com/katorymnd/pawa-pay-integration
Composer,

composer require katorymnd/pawa-pay-integration

Closing note

Dual version support is a calm bridge, not a cliff. Start with V1, test V2 where it counts, and move forward with confidence. If you want a diagram of the V1 to V2 rollout path, say the word and I will add a crisp visual.

pawaPay SDK offers secure, user-friendly mobile money integration for PHP, ideal for African e-commerce.

Mon, 25 Nov 2024 22:51:21 +0000

pawaPay Payment SDK: Streamline Your Payment Processes in PHP

In the fast-paced world of e-commerce and online transactions, efficiency, security, and simplicity are paramount. Integrating payment solutions can often be a complex and time-consuming process, especially when dealing with multiple payment methods across different regions. The pawaPay Payment SDK emerges as a robust solution, specially tailored for PHP applications, aiming to streamline the integration of pawaPay's Mobile Money payment solutions. This lightweight, easy-to-use SDK encapsulates powerful functionalities into a developer-friendly package, enabling seamless payment processes within your applications.

What is pawaPay?

pawaPay is a mobile money payment platform designed to empower businesses to seamlessly send and receive payments across various African countries using mobile wallets. With over 300 million mobile money users in Africa, pawaPay taps into this expansive ecosystem, providing rapid settlements, eliminating chargebacks, and ensuring secure transaction processing—all accessible from a unified dashboard. pawaPay offers integrations with all major mobile money operators, delivering a scalable and efficient solution for businesses aiming to leverage the burgeoning mobile money market in Africa.

Why Mobile Money in Africa?

Mobile money has revolutionized financial transactions in Africa, where traditional banking infrastructure is limited. It allows users to perform financial transactions using their mobile phones, without needing a bank account. This has significantly increased financial inclusion and has become the preferred method of payment for many Africans. By integrating mobile money into your applications, you open your business to a vast and growing market.

Introducing the pawaPay Payment SDK

The pawaPay Payment SDK is a secure and straightforward way to integrate pawaPay's mobile money payment services into PHP applications. By handling the complexities of direct API calls and providing a set of easy-to-implement methods, this SDK allows developers to efficiently process payments without needing deep expertise in payment systems.

Key Benefits

Simplified Integration: Reduce development time with an SDK that abstracts complex API interactions.
Enhanced Security: Leverage built-in security features adhering to the latest standards.
Comprehensive Functionality: Access a wide range of payment operations through simple methods.

Key Features of the pawaPay Payment SDK

Easy to Use

With comprehensive documentation and ready-to-use code snippets, integrating the pawaPay SDK into your existing PHP projects is straightforward. The SDK reduces the complexity involved in coding for mobile money payment systems, allowing you to focus on other critical aspects of your application.

Security at Its Core

Built with security as a priority, the SDK adheres to the latest standards in data encryption, validations, and other security protocols to ensure that all transactions are protected against fraud and breaches.

Comprehensive Payment Functions

Whether you're looking to initiate deposits, manage payouts, process refunds, or check transaction statuses, the SDK covers all bases, providing you with the tools you need to manage various mobile money payment operations efficiently.

Cross-Network Compatibility

The SDK supports integration with all major mobile money operators in Africa, ensuring that your application can process payments regardless of the user's mobile money provider.

System Requirements

Before you begin, ensure that your environment meets the following system requirements:

PHP Version: 8.0 or higher
Composer: PHP dependency manager installed
cURL: Required for making HTTP requests
OpenSSL: For secure HTTPS connections
JSON Extension: Enabled in PHP for working with JSON data
SSL Certification: A valid SSL certificate on your server
Web Server: Apache 2.4, LiteSpeed V8.1, or any modern server capable of running PHP

Installation and Setup

Step 1: Install the SDK via Composer

Begin by installing the SDK using Composer:

composer require katorymnd/pawa-pay-integration

Step 2: Configure Your API Keys

After installation, you need to configure your API keys provided by pawaPay. You can set them in your application's environment variables.

require_once 'vendor/autoload.php';

use Dotenv\Dotenv;
use Katorymnd\PawaPayIntegration\Api\ApiClient;
use Katorymnd\PawaPayIntegration\Utils\Helpers;
use Katorymnd\PawaPayIntegration\Utils\Validator;
use Katorymnd\PawaPayIntegration\Utils\FailureCodeHelper;
use Monolog\Logger;
use Monolog\Handler\StreamHandler;
use Whoops\Run;
use Whoops\Handler\PrettyPageHandler;

// Initialize Whoops error handler for development
$whoops = new Run();
$whoops->pushHandler(new PrettyPageHandler());
$whoops->register();

// Load the environment variables from the .env file
$dotenv = Dotenv::createImmutable(__DIR__ . '/../');
$dotenv->load();


// Set the environment and SSL verification based on the production status
$environment = getenv('ENVIRONMENT') ?: 'sandbox'; // Default to sandbox if not specified
$sslVerify = $environment === 'production';  // SSL verification true in production

// Dynamically construct the API token key
$apiTokenKey = 'PAWAPAY_' . strtoupper($environment) . '_API_TOKEN';

// Get the API token based on the environment
$apiToken = $_ENV[$apiTokenKey] ?? null;


if (!$apiToken) {
    echo json_encode([
        'success' => false,
        'errorMessage' => 'API token not found for the selected environment.'
    ]);
    exit;
}

// Initialize Monolog for logging
$log = new Logger('pawaPayLogger');
$log->pushHandler(new StreamHandler(__DIR__ . '/../logs/payment_success.log', \Monolog\Level::Info));
$log->pushHandler(new StreamHandler(__DIR__ . '/../logs/payment_failed.log', \Monolog\Level::Error));

// Create a new instance of the API client with SSL verification control
$pawaPayClient = new ApiClient($apiToken, $environment, $sslVerify);

Replace 'YOUR_PAWAPAY_API_KEY' with your actual API key provided by pawaPay in your '.env file.

Using the SDK

Initiating a Payment

To initiate a payment, you can use the initiateDeposit method. Here's how:





// Initialize the API client
$pawaPayClient = new ApiClient($apiToken, $environment, $sslVerify);

// Generate a unique transaction ID (UUID v4)
$transactionId = Helpers::generateUniqueId();

// Define payment details
$amount = '1000'; // Payment amount in KES (Kenyan Shilling)
$currency = 'KES'; // Currency code
$correspondent = 'MPESA_KEN'; // Correspondent ID for the MPESA network
$recipientMsisdn = '254712345678'; // Recipient's phone number

// Custom transaction description
$description = 'Payment for invoice -1234';

// Optional metadata for the transaction
$metadata = [
    'order_id' => '1234',
    'customer_id' => '5678',
];

// Step 1: Validate the amount
$validatedAmount = Validator::symfonyValidateAmount($amount);

// Step 2: Validate the description
$validatedDescription = Validator::validateStatementDescription($description);

// Step 3: Validate metadata if provided
if (!empty($metadata)) {
    Validator::validateMetadataItemCount($metadata);
}

// Step 4: Initiate the payment
$response = $pawaPayClient->initiatePayment(
    $transactionId,
    $validatedAmount,
    $currency,
    $correspondent,
    $recipientMsisdn,
    $validatedDescription,
    $metadata
);

// Step 5: Check if the response is successful
if ($response['status'] === 200) {
    // Payment was initiated successfully
    $log->info('Payment initiated successfully', [
        'transactionId' => $transactionId,
        'response' => $response['response'],
    ]);
    echo "Payment initiation successful. Transaction ID: $transactionId";
} else {
    // Payment initiation failed; handle the error
    $log->error('Payment initiation failed', [
        'transactionId' => $transactionId,
        'error' => $response->getErrorMessage(),
    ]);
    echo "Payment initiation failed. Error: " . $response->getErrorMessage();
}

In this example, we initiate a payment of 1000 KES to a recipient on the MPESA network. We check if the response is successful and handle it accordingly.

Checking Transaction Status

To check the status of a transaction:


 // Proceed to check the transaction status
        $statusResponse = $pawaPayClient->checkTransactionStatus($transactionId, 'deposit');

        if ($statusResponse['status'] === 200) {
            $depositInfo = $statusResponse['response'][0]; // Get the deposit info
            $depositStatus = $depositInfo['status'];

Replace 'TRANSACTION_ID_RECEIVED' with the transaction ID you received when initiating the payment.

Handling Errors

The SDK is designed to handle errors gracefully. Here's how you might handle exceptions:

try {
     $response = $pawaPayClient->initiateDeposit(
        $depositId,
        $validatedAmount,
        $currency,
        $mno,
        $payerMsisdn,
        $validatedDescription,
        $metadata
    );

    // Process response
} catch (Exception $e) {
    // Log error details
    error_log('Payment initiation error: ' . $e->getMessage());
    // Inform the user
    echo "An error occurred while processing your payment. Please try again.";
}

Using try-catch blocks allows you to catch exceptions thrown by the SDK and handle them appropriately.

Best Practices

Secure API Keys: Never expose your API keys in your code repositories. Use environment variables or secure configuration files.
Validate User Input: Always validate and sanitize user input to prevent injection attacks.
Error Logging: Implement robust error logging to aid in troubleshooting.
Transaction Monitoring: Regularly monitor transactions to detect any suspicious activity.

Use Cases

E-commerce Platforms

Integrate seamless payment solutions that cater to both sellers and buyers. With pawaPay, customers can pay using their preferred mobile money provider, increasing conversion rates.

Marketplaces

Facilitate secure and reliable transactions between multiple parties with ease. The SDK supports splitting payments and managing payouts to different vendors.

Donation Platforms

Allow donors to contribute easily via mobile money, broadening your reach to users without traditional banking services.

Conclusion

The pawaPay Payment SDK for PHP simplifies the integration of mobile money payment solutions, enabling businesses to tap into the vast African market easily. By abstracting the complexities of payment processing and providing robust security features, the SDK allows developers to focus on building great applications while ensuring seamless and secure transactions.

Whether you're an e-commerce platform, a subscription service, or a marketplace, integrating pawaPay can significantly enhance your payment processing capabilities, reduce development time, and provide a better user experience.

Get Started Today

Visit the pawaPay Payment SDK GitHub Repository to access the SDK, documentation, and examples. Start integrating and unlock new opportunities in the African mobile money ecosystem.