README

A Laravel SDK for integrating PayChangu payment services. This package simplifies the process of initializing payments (Hosted Checkout, Mobile Money, Card, Bank) and managing payouts, bill payments, and airtime.

📚 API Reference: For complete API documentation, visit 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, verify transactions, and process refunds.
Direct Charge (Bank): Initiate bank transfers.
Payouts: Send money to mobile money wallets and bank accounts.
Bill Payments: Validate and pay bills (LWB, ESCOM, etc.).
Airtime: Recharge airtime (TNM, Airtel).
Verification: Verify transactions across all services.
Virtual Accounts (USD): Manage customers and US virtual accounts.

Installation

You can install the package via composer:

composer require paychangu/laravel

Publish the config file:

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

This is the contents of the published config file:

return [
    /*
    |--------------------------------------------------------------------------
    | PayChangu API Private Key
    |--------------------------------------------------------------------------
    |
    | This is the private key used to authenticate with the PayChangu API.
    |
    */
    'private_key' => env('PAYCHANGU_API_PRIVATE_KEY'),

    /*
    |--------------------------------------------------------------------------
    | PayChangu API Base URL
    |--------------------------------------------------------------------------
    |
    | This is the root URL for the PayChangu API.
    | Specific endpoints (checkout, mobile-money) will be constructed from this.
    |
    */
    'api_base_url' => env('PAYCHANGU_API_BASE_URL', 'https://api.paychangu.com/'),
];

Configuration

Add the following variables to your .env file:

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

Usage

1. Hosted Checkout (Payment Link)

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

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',
    'email' => 'customer@example.com',
    'first_name' => 'John',
    'last_name' => 'Doe',
    'meta' => ['order_id' => '123']
]);

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

Verify Checkout Transaction:

$verification = Paychangu::verify_checkout('TXN_1234567890');

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 Transaction Details:

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

4. Card Payments

Charge Card:

$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
]);

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. 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.

paychangu / laravel

Maintainers

Package info

Fund package maintenance!

Statistics

Security