README

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

composer require coinwaka/coinwaka-php

Quickstart

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

use Coinwaka\Coinwaka;

$coinwaka = new Coinwaka(['apiKey' => getenv('COINWAKA_SECRET_KEY')]);

$intent = $coinwaka->paymentIntents->create([
    'amount' => '2500',
    'currency' => 'KES',
    'settlement_currency' => 'USDT',
    'payment_methods' => ['mpesa', 'card', 'coinwaka_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

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

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

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

Verify webhooks

Pass the raw request body.

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

try {
    $event = $coinwaka->webhooks->verify(
        $payload,
        $_SERVER['HTTP_COINWAKA_SIGNATURE'],
        $_SERVER['HTTP_COINWAKA_TIMESTAMP'],
        getenv('COINWAKA_WEBHOOK_SECRET')
    );
    if ($event['type'] === 'payment_intent.paid') {
        // fulfil the order (dedupe on $event['id'])
    }
    http_response_code(200);
} catch (\Coinwaka\CoinwakaError $e) {
    http_response_code(400);
}

Errors

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

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

License

MIT