Documentation/PHP SDK
SERVER-SIDE PHP

PayCow
PHP SDK

A dependency-free PHP client for creating hosted USDT payments, retrieving their current status, and verifying signed PayCow webhooks with the exact API contract used by the backend.

PHP

paycow/paycow-php-sdk

Downloadable PHP 7.4+ package with a standalone PSR-4 autoloader.

PHP 7.4+PSR-4ZERO EXTERNAL PACKAGESCURL + JSON

Installation

Download and extract the archive into your application. The included autoloader makes the SDK usable immediately without publishing or installing another package.

require_once __DIR__ . '/paycow-php-sdk/autoload.php';

Keep the API key, API secret, and webhook secret in server-side environment variables.

PAYCOW_API_KEY=your_api_key
PAYCOW_API_SECRET=your_api_secret
PAYCOW_WEBHOOK_SECRET=whsec_your_signing_secret

Create a payment

payments()->create() calls POST /api/payment/create. Amounts remain decimal strings and the optional idempotency key is sent in both the header and request body.

<?php

require_once __DIR__ . '/paycow-php-sdk/autoload.php';

use PayCow\PayCowClient;

$paycow = new PayCowClient([
    'api_key' => getenv('PAYCOW_API_KEY'),
    'api_secret' => getenv('PAYCOW_API_SECRET'),
]);

$payment = $paycow->payments()->create([
    'userId' => 'customer-2048',
    'amount' => '50.00',
    'network' => 'TRC20',
    'addressSerialNo' => 'WAL-1002',
    'idempotencyKey' => 'order-2048-001',
]);

echo $payment->getSessionId();
echo $payment->getPaymentUrl();
echo $payment->getPayableAmount();
echo $payment->getDepositAddress();
Send the customer to getPaymentUrl() and display getPayableAmount() when the exact transfer amount is needed. For eligible Pro, Scale and Enterprise merchants, set paymentMethod to ONRAMP when creating a payment (default: ONCHAIN). The buyer enters the exact payableAmount in the external provider’s “You get” USDT field; PayCow verifies the on-chain receipt.

Retrieve payment status

payments()->getStatus() calls the authenticated GET /api/payment/status/:sessionId endpoint.

$payment = $paycow->payments()->getStatus('66ce30d74c0c51a48f2d2903');

if ($payment->isPaid()) {
    creditBalanceOnce(
        $payment->getUserId(),
        $payment->getPaymentReference()
    );
}

if ($payment->isConfirming()) {
    echo $payment->getConfirmations();
}

The status model exposes the session ID, merchant reference, customer ID, requested and payable amounts, received amount, network, address, confirmations, transaction hash, and timestamps returned by PayCow.

Verify webhooks

Pass the unchanged request body and request headers to the verifier. It supports both normal header arrays and PHP $_SERVER header keys.

<?php

require_once __DIR__ . '/paycow-php-sdk/autoload.php';

use PayCow\PayCowClient;

$paycow = new PayCowClient([
    'api_key' => getenv('PAYCOW_API_KEY'),
    'api_secret' => getenv('PAYCOW_API_SECRET'),
]);

$rawBody = file_get_contents('php://input');
$headers = function_exists('getallheaders') ? getallheaders() : $_SERVER;
$event = $paycow->webhooks()->verify(
    $rawBody,
    $headers,
    getenv('PAYCOW_WEBHOOK_SECRET')
);

if ($event->isPaid()) {
    creditBalanceOnce(
        $event->getUserId(),
        $event->getPaymentReference()
    );
}

http_response_code(200);

The verifier accepts PayCow-Timestamp and PayCow-Signature, validates the v1=<64 hexadecimal characters> format, computes HMAC-SHA256 over timestamp.rawBody, uses hash_equals, and applies a 300-second freshness window.

Error handling

Invalid API credentials raise AuthenticationException. Other HTTP failures raise ApiException with the response status and raw body.

use PayCow\Exceptions\ApiException;
use PayCow\Exceptions\AuthenticationException;

try {
    $payment = $paycow->payments()->getStatus($sessionId);
} catch (AuthenticationException $error) {
    error_log($error->getMessage());
    throw $error;
} catch (ApiException $error) {
    error_log((string) $error->getStatusCode());
    error_log((string) $error->getResponseBody());
    throw $error;
}

API contract

SDK methodBackend endpointRequired values
payments()->createPOST /api/payment/createuserId, amount, network
payments()->getStatusGET /api/payment/status/:idsessionId
webhooks()->verifyLocal verificationRaw body, headers, secret