PayChangu PHP SDK

A PHP SDK for PayChangu with first-class Laravel support. Use it in a Laravel app via the facade and config, or in any PHP application by constructing the client with your secret key.

📚 API Reference: PayChangu Developer Docs

Features

• Hosted Checkout: Generate checkout URLs for easy payments.
• Mobile Money: Charge mobile money wallets (Airtel Money, Mpamba) directly.
• Card Payments: Charge cards (including 3DS), verify transactions, and process refunds.
• Direct Charge (Bank): Initiate bank transfers and verify them.
• Payouts: Send money to mobile money wallets and bank accounts.
• Bill Payments: Validate and pay bills (LWB, ESCOM, etc.).
• Airtime: Recharge airtime (TNM, Airtel).
• Balance: Retrieve wallet balances by currency.
• Connect: Generate Connect links and act on behalf of connected merchants.
• Webhooks: Verify HMAC-SHA256 webhook signatures.
• Virtual Accounts (USD): Manage customers and US virtual accounts.

Frontend-only PayChangu products are not part of this SDK: Inline Checkout, Drop-in Element, HTML Checkout, and plugins such as WooCommerce, GiveWP, and WHMCS.

Installation

composer require paychangu/laravel

Laravel

Publish the config file:

php artisan vendor:publish --tag="paychangu-config"

This is the contents of the published config file:

return [
    'private_key' => env('PAYCHANGU_API_PRIVATE_KEY'),
    'api_base_url' => env('PAYCHANGU_API_BASE_URL', 'https://api.paychangu.com/'),
    'webhook_secret' => env('PAYCHANGU_WEBHOOK_SECRET'),
];

Add the following variables to your .env file:

PAYCHANGU_API_PRIVATE_KEY=your_private_key_here
PAYCHANGU_WEBHOOK_SECRET=your_webhook_secret_here
# Optional: Override Base URL (Defaults to https://api.paychangu.com/)
PAYCHANGU_API_BASE_URL=https://api.paychangu.com/

Laravel usage stays the same:

use Paychangu\Laravel\Facades\Paychangu;

$response = Paychangu::create_checkout_link([
    'amount' => 5000,
    'currency' => 'MWK',
    'return_url' => 'https://yoursite.com/success',
    'callback_url' => 'https://yoursite.com/callback',
]);

Vanilla PHP

No Laravel install is required. Pass your secret key (and optionally the base URL) to the constructor:

use Paychangu\Laravel\Paychangu;

$paychangu = new Paychangu('your_private_key_here');

$response = $paychangu->create_checkout_link([
    'amount' => 5000,
    'currency' => 'MWK',
    'return_url' => 'https://yoursite.com/success',
    'callback_url' => 'https://yoursite.com/callback',
    'email' => 'customer@example.com',
]);

You can also rely on environment variables (PAYCHANGU_API_PRIVATE_KEY, PAYCHANGU_API_BASE_URL, PAYCHANGU_WEBHOOK_SECRET) instead of constructor arguments.

The examples below use the Laravel facade. In a PHP app, call the same methods on your $paychangu instance.

Usage

1. Hosted Checkout (Payment Link)

Use this to redirect users to a PayChangu hosted page. Required fields: amount, callback_url, return_url.

You may pass your own unique tx_ref (and optional uuid). If omitted, the SDK generates them.

use Paychangu\Laravel\Facades\Paychangu;

$response = Paychangu::create_checkout_link([
    'amount' => 5000,
    'currency' => 'MWK',
    'return_url' => 'https://yoursite.com/success',
    'callback_url' => 'https://yoursite.com/callback',
    'tx_ref' => 'ORDER-123',
    'email' => 'customer@example.com',
    'first_name' => 'John',
    'last_name' => 'Doe',
    'meta' => ['order_id' => '123']
]);

if ($response['success']) {
    return redirect($response['checkout_url']);
}

Verify Checkout Transaction:

$verification = Paychangu::verify_checkout('ORDER-123');

2. Mobile Money Payments

Get Supported Operators:

$operators = Paychangu::mobile_money_operators();

Charge Mobile Money Wallet:

$response = Paychangu::create_mobile_money_payment([
    'mobile' => '0999123456', // Phone number in format 265... or 099...
    'mobile_money_operator_ref_id' => 'mpamba_ref_id', // Get from mobile_money_operators()
    'amount' => 1000,
    'charge_id' => 'unique_charge_id_123', // Must be unique for every transaction
]);

Verify Payment:

$verification = Paychangu::verify_mobile_money_payment('unique_charge_id_123');

Get Payment Details:

$details = Paychangu::get_mobile_money_payment_details('unique_charge_id_123');

3. Direct Charge (Bank Transfer)

Initiate Bank Charge:

$response = Paychangu::create_direct_charge_payment([
    'currency' => 'MWK', // Currency code (e.g., 'MWK', 'USD')
    'amount' => 50000,
    'payment_method' => 'mobile_bank_transfer',
    'charge_id' => 'bank_charge_001', // Must be unique for every transaction
]);

Get / verify transaction details:

$details = Paychangu::get_direct_charge_details('bank_charge_001');
$verification = Paychangu::verify_direct_charge_payment('bank_charge_001');

4. Card Payments

Charge Card:

Successful charges may require 3DS. When requires_3ds_auth is true, redirect the customer to 3ds_auth_link.

$response = Paychangu::create_card_payment([
    'card_number' => '4000123456789010',
    'expiry' => '12/25', // Format: MM/YY
    'cvv' => '123',
    'cardholder_name' => 'John Doe',
    'amount' => 5000,
    'currency' => 'MWK',
    'charge_id' => 'card_charge_001', // Must be unique for every transaction
    'redirect_url' => 'https://yoursite.com/card-callback', // URL to redirect after payment
]);

if ($response['success'] && ! empty($response['data']['requires_3ds_auth'])) {
    return redirect($response['data']['3ds_auth_link']);
}

Verify Card Charge:

$verification = Paychangu::verify_card_payment('card_charge_001');

Refund Card Charge:

$refund = Paychangu::refund_card_payment('card_charge_001');

5. Mobile Money Payouts

Get Payout Operators:

$operators = Paychangu::mobile_money_payout_operators();

Initialize Payout:

$response = Paychangu::create_mobile_money_payout([
    'mobile' => '0888123456', // Phone number in format 265... or 088...
    'mobile_money_operator_ref_id' => 'airtel_money_ref_id', // Get from mobile_money_payout_operators()
    'amount' => 2000,
    'charge_id' => 'payout_001', // Must be unique for every transaction
    // Optional fields:
    // 'email' => 'customer@example.com',
    // 'first_name' => 'John',
    // 'last_name' => 'Doe',
]);

Get Payout Details:

$details = Paychangu::get_mobile_money_payout_details('payout_001');

6. Bank Payouts

Get Supported Banks:

$banks = Paychangu::get_supported_banks_for_payout('MWK');

Initialize Bank Payout:

$response = Paychangu::create_bank_payout([
    'bank_uuid' => 'bank_uuid_here', // Get from get_supported_banks_for_payout()
    'amount' => 100000,
    'charge_id' => 'bank_payout_001', // Must be unique
    'bank_account_name' => 'Jane Doe',
    'bank_account_number' => '100200300',
    // Optional fields:
    // 'payout_method' => 'bank_transfer', // Defaults to 'bank_transfer' if not provided
    // 'email' => 'customer@example.com',
    // 'first_name' => 'Jane',
    // 'last_name' => 'Doe',
]);

Get Payout Details:

$details = Paychangu::get_bank_payout_details('bank_payout_001');

List All Bank Payouts:

$allPayouts = Paychangu::get_all_bank_payouts();

7. Bill Payments

Get Billers:

$billers = Paychangu::get_billers();

Get Biller Details:

$billerDetails = Paychangu::get_biller_details('ESCOM');

Validate Bill:

$validation = Paychangu::validate_bill([
    'biller' => 'ESCOM',
    'account' => '123456789',
]);

Pay Bill:

$payment = Paychangu::pay_bill([
    'biller' => 'ESCOM',
    'account' => '123456789',
    'amount' => 5000,
    'reference' => 'bill_payment_001',
]);

Some billers may accept optional amount/reference fields depending on bill type.

Get Transaction Details:

$details = Paychangu::get_bill_transaction('bill_payment_001');

Get Statistics:

$stats = Paychangu::get_bill_statistics();

8. Airtime

Buy Airtime:

$airtime = Paychangu::buy_airtime([
    'phone' => '0888123456',
    'amount' => 1000,
    'reference' => 'airtime_ref_001',
]);

reference is optional.

9. Wallet Balance

$balance = Paychangu::get_balance('MWK');

10. PayChangu Connect

Generate a Connect authorization URL, then redirect your user. After they authorize, PayChangu redirects back with an access token. Use that token to charge on their behalf.

Token revoke from the API is not published yet; merchants can revoke connected apps from the PayChangu dashboard.

$link = Paychangu::create_connect_link([
    'client_id' => 'your_app_client_id',
    'redirect_uri' => 'https://yoursite.com/connect/callback',
    'mode' => 'live', // or 'test'
    'scope' => 'payments:write payments:read',
    'wh_url' => 'https://yoursite.com/webhooks/paychangu',
    'wh_secret' => 'your_connect_webhook_secret',
]);

$user = Paychangu::get_connect_user($accessToken);

$connected = Paychangu::getFacadeRoot()->withAccessToken($accessToken);
$connected->create_checkout_link([/* ... */]);

In vanilla PHP:

$connected = $paychangu->withAccessToken($accessToken);
$connected->create_checkout_link([/* ... */]);

11. Webhooks

Verify the Signature header with an HMAC-SHA256 of the raw request body using your webhook secret. After a valid webhook, re-query the matching verify/details endpoint before fulfilling an order.

$payload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_SIGNATURE'] ?? '';

if (! Paychangu::verify_webhook($payload, $signature)) {
    http_response_code(403);
    exit;
}

$event = Paychangu::parse_webhook($payload, $signature);

if (($event['event_type'] ?? null) === 'api.charge.payment') {
    $verification = Paychangu::verify_mobile_money_payment($event['charge_id']);
}

Laravel example:

use Illuminate\Http\Request;
use Paychangu\Laravel\Facades\Paychangu;

public function handle(Request $request)
{
    $payload = $request->getContent();
    $signature = $request->header('Signature', '');

    $event = Paychangu::parse_webhook($payload, $signature);

    // Re-query PayChangu before fulfilling the order.

    return response()->noContent();
}

12. Virtual Accounts (USD)

Create Customer:

$customer = Paychangu::create_virtual_account_customer([
    'email' => 'john@example.com',
    'first_name' => 'John',
    'last_name' => 'Banda',
]);

List Customers:

$customers = Paychangu::get_virtual_account_customers([
    'page' => 1,
    'per_page' => 20,
]);

Get Customer:

$customer = Paychangu::get_virtual_account_customer('customer_id_here');

Update Customer:

$updated = Paychangu::update_virtual_account_customer('customer_id_here', [
    'email' => 'new-email@example.com',
]);

Delete Customer:

$deleted = Paychangu::delete_virtual_account_customer('customer_id_here');

Create US Account (Virtual IBAN):

$account = Paychangu::create_us_account('customer_id_here');

Deactivate/Reactivate US Account:

$deactivated = Paychangu::deactivate_us_account('customer_id_here');
$reactivated = Paychangu::reactivate_us_account('customer_id_here');

US Account Activity:

$activity = Paychangu::us_account_activity('customer_id_here');

Testing

composer test

Contributing

Please see CONTRIBUTING for details.

Credits

• Mzati

Support

For support, email developer@paychangu.com or visit our support page.

License

The MIT License (MIT). Please see License File for more information.