README

Official CowriePay PHP SDK: a signed client for the CowriePay Developer API (/v2) plus webhook signature verification. Server-side only (your cpk_* secret must never reach a browser or mobile app). Zero Composer runtime dependencies (ext-curl + ext-json only). PHP ≥ 8.1.

Install

composer require cowriepay/cowriepay-php

Quickstart

use CowriePay\CowriePay;

$cowriepay = new CowriePay(
    apiKey: getenv('CPK_KEY'),      // cpk_test_… or cpk_live_…
    apiSecret: getenv('CPK_SECRET'),
);
// One base URL for everything: https://api.cowriepay.io
// The key you use selects the network, no host switch:
//   cpk_test_… → Sandbox (testnets: TRON Nile, BSC testnet, ETH Sepolia; fund from faucets)
//   cpk_live_… → Live (mainnets, real funds)
// Same code for both; swap the key to go live. Override the host with baseUrl: '…' (e.g. a dev host).

$wallet = $cowriepay->wallets->create(
    ['chain' => 'TRON', 'asset' => 'USDT_TRON'],
    idempotencyKey: bin2hex(random_bytes(16)), // makes the POST safe to auto-retry
);

$balances = $cowriepay->transactions->balances();
$deposits = $cowriepay->transactions->listDeposits(['status' => 'CONFIRMED', 'limit' => 20]);

Namespaces: wallets, customers, transactions (deposits / withdrawals / balances), withdrawals, fees, webhooks, apiKeys, health. Responses are associative arrays (the OpenAPI spec is the type reference). For anything not wrapped, $cowriepay->request($method, $path, body: [...]) is a signed escape hatch.

CowriePay ships WaaS-first: this SDK targets the WaaS-only API view, so it does not include the checkout surface (payment intents / refunds). Those appear when checkout launches, no code change.

Errors

Every non-2xx response throws a typed exception carrying ->errorCode and ->status:

use CowriePay\Exceptions\{NotFoundException, AuthenticationException, CowriePayException};

try {
    $cowriepay->wallets->get('does-not-exist');
} catch (NotFoundException $e) {           // 404 / FEATURE_NOT_AVAILABLE
} catch (AuthenticationException $e) {      // 401 INVALID_SIGNATURE / TIMESTAMP_EXPIRED / …
} catch (CowriePayException $e) {
    error_log("{$e->errorCode} {$e->status} {$e->requestId}");
}

Verifying webhooks

Verify against the raw request body. During a secret rotation, pass both the current and previous secrets so no delivery is rejected while you roll the secret.

$ok = CowriePay::verifyWebhook(
    payload: $rawBody,                                  // the RAW request body
    signatureHeader: $_SERVER['HTTP_X_COWRIEPAY_SIGNATURE'],
    timestamp: $_SERVER['HTTP_X_COWRIEPAY_TIMESTAMP'],
    secrets: [getenv('WEBHOOK_SECRET')],                // add the previous secret during rotation
    toleranceSeconds: 300,                              // optional replay guard
);

Development

composer install
composer test    # PHPUnit: golden vectors + prove-it-fails + client behaviour
composer stan    # PHPStan (max)

License

MIT, Copyright (c) 2026 COWRIEX SAS. See LICENSE.

CowriePay and COWRIEX are trademarks of COWRIEX SAS. This license covers the source code only and grants no right to the COWRIEX or CowriePay names or logos.