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.
paycow/paycow-php-sdk
Downloadable PHP 7.4+ package with a standalone PSR-4 autoloader.
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();
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 method | Backend endpoint | Required values |
|---|---|---|
payments()->create | POST /api/payment/create | userId, amount, network |
payments()->getStatus | GET /api/payment/status/:id | sessionId |
webhooks()->verify | Local verification | Raw body, headers, secret |