PHP SDK - Pycer

The official Pycer PHP SDK provides a typed client for the Merchant API, a webhook verification helper, and automatic error handling.

Installation

composer require pycer/php-sdk

Requires PHP 8.3+ (matching Pycer’s runtime).

Creating a payment

use Pycer\SDK\Client;

$client = new Client(
    apiKey:  $_ENV['PYCER_API_KEY'],
    baseUrl: $_ENV['PYCER_BASE_URL'],
);

$payment = $client->payments()->create([
    'amount'         => '50.00',
    'currency'       => 'USD',
    'customer_email' => 'customer@example.com',
    'customer_name'  => 'Jane Doe',
    'description'    => 'Order #1042',
    'metadata'       => ['order_id' => '1042'],
    'redirect_url'   => 'https://your-store.com/callback',
    'cancel_url'     => 'https://your-store.com/cancel',
]);

// $payment['data']['checkout_url'] - redirect customer here
// $payment['data']['id']           - store for later verification
header('Location: ' . $payment['data']['checkout_url']);
exit;

Verifying a payment

After the customer returns from checkout, verify the payment status before fulfilling the order:

$payment = $client->payments()->get('pay_abc123');

if ($payment['data']['status'] === 'completed') {
    fulfillOrder($payment['data']['metadata']['order_id']);
} else {
    echo 'Payment not completed. Status: ' . $payment['data']['status'];
}

Listing transactions

$transactions = $client->transactions()->list([
    'status'  => 'completed',
    'page'    => 1,
    'per_page' => 20,
]);

foreach ($transactions['data']['data'] as $txn) {
    printf("%s  %s %s\n", $txn['id'], $txn['amount'], $txn['currency']);
}

Webhook handling with SDK helper

The SDK includes a Webhook class that handles signature verification and event parsing. See Webhooks for the canonical verification reference.

use Pycer\SDK\Webhook;

$rawBody   = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_PYCER_SIGNATURE'] ?? '';
$timestamp = (int) ($_SERVER['HTTP_X_PYCER_TIMESTAMP'] ?? 0);

$webhook = new Webhook($_ENV['PYCER_WEBHOOK_SECRET']);

try {
    $event = $webhook->verify($rawBody, $signature, $timestamp);
} catch (\Pycer\SDK\Exceptions\InvalidSignatureException $e) {
    http_response_code(401);
    exit('Invalid signature');
} catch (\Pycer\SDK\Exceptions\StaleEventException $e) {
    http_response_code(403);
    exit('Timestamp too old');
}

// Route by event type
if ($event->type === 'payment.completed') {
    fulfillOrder($event->data['metadata']['order_id'] ?? '');
}

http_response_code(200);

Error handling

The SDK throws typed exceptions for every error category:

use Pycer\SDK\Exceptions\{
    AuthenticationException,
    ValidationException,
    NotFoundException,
    RateLimitException,
    PycerException,
};

try {
    $payment = $client->payments()->create($payload);
} catch (AuthenticationException $e) {
    // 401 - check your API key
} catch (ValidationException $e) {
    // 422 - $e->getFields() returns the field-level errors array
    foreach ($e->getFields() as $fieldError) {
        echo $fieldError['field'] . ': ' . $fieldError['message'];
    }
} catch (RateLimitException $e) {
    // 429 - retry after $e->getRetryAfter() seconds
    sleep($e->getRetryAfter());
} catch (PycerException $e) {
    // Any other Pycer error
    error_log($e->getMessage());
}

Environment configuration

# .env
PYCER_BASE_URL=https://pycer.quantivogroup.com
PYCER_API_KEY=op_live_abc123.def456
PYCER_WEBHOOK_SECRET=whsec_abc123...