Introducing the Pesapal PHP SDK: Simplify Your Payment Integration

Integrating payment solutions into your PHP applications just got a whole lot easier. We are thrilled to announce the release of our Pesapal PHP SDK, a robust and user-friendly library designed to streamline your interaction with the Pesapal payment gateway.

🌟 Why Pesapal PHP SDK?

Pesapal is a leading payment platform in Africa, offering secure and reliable payment processing for businesses of all sizes. However, integrating Pesapal's API directly can be time-consuming and complex. Our SDK abstracts the intricacies of the API, providing a clean and intuitive interface for developers.

Key Features

Easy Authentication: Simplifies OAuth authentication with Pesapal.
Seamless Payment Integration: Quickly initiate payments and handle callbacks.
Transaction Management: Easily check transaction statuses and process refunds.
PSR-4 Compliant: Follows PHP-FIG standards for autoloading.
Extensive Documentation: Well-documented methods and examples to get you started.

🚀 Getting Started

Installation

Install the SDK via Composer:

composer require katorymnd/pesapal-php-sdk

Requirements

PHP 8.0 or higher
Composer
Pesapal Merchant Account

Configuration

Initialize the client with your Pesapal credentials:

require 'vendor/autoload.php';

use Katorymnd\PesapalPhpSdk\Api\PesapalClient;
use Katorymnd\PesapalPhpSdk\Config\PesapalConfig;

$consumerKey = 'YOUR_CONSUMER_KEY';
$consumerSecret = 'YOUR_CONSUMER_SECRET';

// Initialize PesapalConfig and PesapalClient
$configPath = __DIR__ . '/../pesapal_dynamic.json';
$config = new PesapalConfig($consumerKey, $consumerSecret, $configPath);
$environment = 'sandbox';
$sslVerify = false; // Enable SSL verification for production


$pesapal = new PesapalClient($config, $environment, $sslVerify);

💳 Initiating a Payment

Here's how you can initiate a payment with minimal code:

use Katorymnd\PesapalPhpSdk\Utils\PesapalHelpers;

$merchantReference = PesapalHelpers::generateMerchantReference();
$notificationId = 'adbd39cc-a48e-4789-b42b-79ad8deb32df';  // Replace with actual notification ID from IPN registration

// Define the order data as an associative array for the POST request
$paymentDetails= [
    "id" => $merchantReference,
    "currency" => "USD",
    "amount" => 100.00,
    "description" => "Payment for invoice " . $merchantReference,
    "callback_url" => "https://www.example.com/payment-callback",
    "notification_id" => $notificationId,
    "redirect_mode" => "PARENT_WINDOW",
    "cancellation_url" => "https://www.example.com/payment-cancel",
    "billing_address" => [
        "phone_number" => "0700000000",
        "email_address" => "john.doe@example.com",
        "country_code" => "UG",
        "first_name" => "John",
        "middle_name" => "",
        "last_name" => "Doe",
        "line_1" => "123 Example Street",
        "line_2" => "",
        "city" => "Kampala",
        "state" => "KMP",
        "postal_code" => 256
    ]
];

// Obtain a valid access token
    $accessToken = $clientApi->getAccessToken();
    if (!$accessToken) {
        throw new PesapalException('Failed to obtain access token');
    }

// Submit order request to Pesapal
    $response = $clientApi->submitOrderRequest($orderData);

if ($response['status'] === 200 && isset($response['response']['redirect_url'])) {
        $redirectUrl = $response['response']['redirect_url'];
        $orderTrackingId = $response['response']['order_tracking_id'];

} else {
    // Handle errors
    $response['response']['error']
}

🔍 Checking Transaction Status

To check the status of a transaction:

use Katorymnd\PesapalPhpSdk\Exceptions\PesapalException;

// Obtain a valid access token
    $accessToken = $clientApi->getAccessToken();
    if (!$accessToken) {
        throw new PesapalException('Failed to obtain access token');
    }

 // Get the transaction status
    $response = $clientApi->getTransactionStatus($orderTrackingId);

if ($response['status'] === 200 && isset($response['response'])) {
        $transactionStatusData = $response['response'];
}

💰 Processing Refunds

Issue a refund with ease:


// Prepare refund data with user-provided values
$refundData = [
    'confirmation_code' => '7323605385336397404011', // the code is received by  checking the transaction status
    'amount' => 50.00,
    'username' => 'John Doe',
    'remarks' => 'Customer Requested Refund'
];

try {
    // Request Refund
    $refundResponse = $clientApi->requestRefund($refundData);

    if ($refundResponse['status'] === 200 && isset($refundResponse['response'])) {
        $refundDataResponse = $refundResponse['response'];

        // Add refund response to the output
        $responseData['refund_response'] = $refundDataResponse;
    } else {
        $errorMessage = $refundResponse['response']['error']['message'] ?? 'Unknown error occurred while requesting a refund.';
        throw new PesapalException($errorMessage);
    }
} catch (PesapalException $e) {
    // Add the error to the response
    $responseData['refund_error'] = [
        'error' => $e->getMessage(),
        'details' => $e->getErrorDetails(),
    ];
}

🧪 Testing and Development

We have included a comprehensive test suite to ensure the reliability of the SDK. To run the tests:

vendor/bin/phpunit

📄 Documentation

For detailed information on all available methods and features, please refer to our GitHub repository.

🤝 Contributing

We welcome contributions from the community! Feel free to submit issues, fork the repository, and make pull requests.

📦 Package Distribution

The SDK is available on Packagist, making it easy to include in your projects via Composer.

🛠️ Continuous Integration

We have set up continuous integration using GitHub Actions to ensure that every update maintains the highest quality standards.

🎉 Conclusion

The Pesapal PHP SDK is designed to save you time and effort, allowing you to focus on building great applications without worrying about the complexities of payment integration. We are excited to see what you build with it!

📫 Stay in Touch

GitHub: github.com/katorymnd/pesapal-php-sdk
Packagist: packagist.org/packages/katorymnd/pesapal-php-sdk

Blog