README

Official PHP SDK for the Mavunta Pay API. No third-party dependencies (ext-curl + ext-json), PHP 8.1+.

composer require mavunta/mavunta-php

Quickstart

Create an intent, redirect the customer to its hosted checkout, and fulfil the order on the signed payment_intent.paid webhook.

use Mavunta\Mavunta;

$mavunta = new Mavunta(['apiKey' => getenv('MAVUNTA_SECRET_KEY')]);

$intent = $mavunta->paymentIntents->create([
    'amount' => '2500',
    'currency' => 'KES',
    'settlement_currency' => 'USDT',
    'payment_methods' => ['mpesa', 'card', 'mavunta_balance'],
    'merchant_reference' => 'ORDER-1001',
]);

header('Location: ' . $intent['checkout_url']);

A cwk_test_… key runs in sandbox (no real money); a cwk_live_… key is live. Every create call sends an Idempotency-Key automatically, so an automatic retry (on 429/5xx) never double-charges.

Resources

$mavunta->auth->verify();
$mavunta->rates->retrieve();
$mavunta->quotes->create(['source_currency' => 'KES', 'target_asset' => 'USDT', 'amount' => '2500']);

$mavunta->paymentIntents->create($params, ['idempotencyKey' => 'order-1001']);
$mavunta->paymentIntents->retrieve('pi_...');
$mavunta->paymentIntents->all(['limit' => 20, 'status' => 'paid']);
$mavunta->paymentIntents->cancel('pi_...');
$mavunta->paymentIntents->refundRequest('pi_...', ['reason' => 'Customer returned item']);

$mavunta->paymentLinks->create(['title' => 'Deposit', 'amount' => '15000', 'currency' => 'KES']);
$mavunta->paymentLinks->retrieve('pl_...');

Verify webhooks

Pass the raw request body.

$payload = file_get_contents('php://input');

try {
    $event = $mavunta->webhooks->verify(
        $payload,
        $_SERVER['HTTP_MAVUNTA_SIGNATURE'],
        $_SERVER['HTTP_MAVUNTA_TIMESTAMP'],
        getenv('MAVUNTA_WEBHOOK_SECRET')
    );
    if ($event['type'] === 'payment_intent.paid') {
        // fulfil the order (dedupe on $event['id'])
    }
    http_response_code(200);
} catch (\Mavunta\MavuntaError $e) {
    http_response_code(400);
}

Errors

try {
    $mavunta->paymentIntents->create(['amount' => '0', 'currency' => 'KES']);
} catch (\Mavunta\MavuntaError $e) {
    error_log($e->type . ' ' . $e->apiCode . ' ' . $e->getMessage() . ' ' . $e->getRequestId());
}

The full contract is published as OpenAPI at https://www.mavunta.com/openapi.yaml.

License

MIT