PHP

Community SDK. affiliatecom/zeroclick-sdk-sellers-php is built and maintained by Affiliate.com, not by ZeroClick. We list it because PHP sellers asked for one and this one is good — we verified its signature handling against our own conformance vectors (see below) — but it is outside our release process, and we do not review its updates. Treat version upgrades as you would any third-party dependency.This page gets you integrated. For the full API, the maintainer’s documentation is the authority, and issues belong on their tracker.

Install

composer require affiliatecom/zeroclick-sdk-sellers-php

Requires PHP 8.3+. It needs a PSR-18 HTTP client and PSR-17 factories; if you have none yet, add a pair:

composer require guzzlehttp/guzzle nyholm/psr7

Configure

Two values, and the first is two values in one. The signing credential is a key id and a secret joined by a colon — pasting in the secret alone is the common setup mistake.

ZEROCLICK_SIGNING_SECRETS=<key-id>:<signing-secret>
ZEROCLICK_API_KEY=zc_live_...

Both come from your seller settings. Keys and secrets covers rotation, which the format supports: comma-separate the pairs and both verify during the overlap.

Wire the client, once

use AffiliateCom\ZeroClick\Sellers\Config\Credentials;
use AffiliateCom\ZeroClick\Sellers\Http\RefusalFactory;
use AffiliateCom\ZeroClick\Sellers\Http\ServerRequestVerifier;
use AffiliateCom\ZeroClick\Sellers\Http\Transport;
use AffiliateCom\ZeroClick\Sellers\SellerClient;
use AffiliateCom\ZeroClick\Sellers\Signature\SignatureVerifier;
use AffiliateCom\ZeroClick\Sellers\Signature\SystemClock;
use Nyholm\Psr7\Factory\Psr17Factory;

$psr17 = new Psr17Factory();
$credentials = Credentials::fromEnvironment(getenv());
$refusals = new RefusalFactory($psr17, $psr17);

$client = new SellerClient(
    credentials: $credentials,
    transport: Transport::discover(),
    verifier: new ServerRequestVerifier(
        verifier: new SignatureVerifier(
            secrets: $credentials->signingSecrets,
            refusals: $refusals,
            clock: new SystemClock(),
        ),
        refusals: $refusals,
    ),
    refusals: $refusals,
);

On Laravel or Symfony you write none of that — the package ships a service provider and a bundle that assemble it from config. See the maintainer’s middleware guide.

Guard a paid route

The PSR-15 middleware performs the whole sequence in the order that matters, so no route can get it wrong or forget the last step:

use AffiliateCom\ZeroClick\Sellers\Http\GuardMiddleware;
use AffiliateCom\ZeroClick\Sellers\Usage\UsageItem;

$guard = new GuardMiddleware($client, 'product-watch', [UsageItem::of('requests', 1)]);

$response = $guard->process($request, $yourHandler);

A denied request comes back as the refusal, your handler never runs, and nothing is billed. A served one carries zc-usage, which is what turns the work into revenue.

When the cost is not known upfront

Declare a ceiling, then settle the real amount. ZeroClick authorises up to the ceiling and bills what you settle, so a ceiling never overcharges:

use AffiliateCom\ZeroClick\Sellers\Usage\SyncUsageItem;
use AffiliateCom\ZeroClick\Sellers\Usage\UsageItem;

$result = $client->guard($request, 'product-watch', [UsageItem::upTo('rows', 500)]);
if ($result->isDenied()) {
    return $result->response();
}

$rows = doTheWork($request);

return $client->withUsage($yourResponse, [
    SyncUsageItem::of('product-watch', 'rows', count($rows)),
]);

A ceiling does gate the buyer’s authorisation, though: the reserve is the ceiling, so a buyer whose per-call cap is below it is refused before any work happens. Keep it near a realistic worst case rather than as high as possible.

Free endpoints that still need a caller

$result = $client->guardIdentity($request, 'product-watch');

No allowance call and no zc-usage. See free and identity endpoints.

Three things that cost money quietly

The maintainer documents these prominently, and they are worth repeating because each is a silent failure rather than an error in a log:

The default serves work you may never bill. When the allowance API gives no usable answer, the package serves the request anyway — matching every official SDK, so a ZeroClick outage does not become your outage. Watch it with onAllowanceUnavailable, or choose OutagePolicy::Deny if refusing costs you less than serving for free.
An unreported ceiling settles at zero. upTo() authorises up to a limit and charges what you settle. Deliver without settling and that is zero — free for the buyer, unbilled for you, no error anywhere.
A normalised request target fails verification. ZeroClick signs the percent-encoded path and query exactly as sent. A framework or an ingress that decodes or reorders them breaks verification for those URLs only, in production only, as an unexplained 401. The package faults loudly on the framework case; the proxy case is a deployment concern — nginx and several managed load balancers normalise %2F by default. See the maintainer’s raw request target.

What we verified

We ran our shared signing conformance vectors — the same 29 cases every official SDK is checked against, including malformed-header and tampered-body cases — against this package, and all 29 agreed. That covers signature verification: the part where a mistake means serving forged traffic. Two gaps to plan around, neither a defect:

No stateful account helpers. If you sell accounts and API keys rather than metering per call, implement those two routes yourself against the reference.
It carries runtime dependencies — PSR HTTP interfaces, php-http/discovery, psr/clock — where the official SDKs deliberately carry none. They land in your composer.json beside your own.

The maintainer also marks their catalog and analytics surfaces as unverified against a live server. Those are additions beyond what any official SDK offers; confirm them against a sandbox before depending on them.

If you would rather not take a dependency

The REST walkthrough implements the same contract with plain HTTP and your standard library. The whole guard is one HMAC check and one HTTPS call.

Overview

TypeScript

Python

Go

Ruby

PHP (community)

Install

Configure

Wire the client, once

Guard a paid route

When the cost is not known upfront

Free endpoints that still need a caller

Three things that cost money quietly

What we verified

If you would rather not take a dependency

​Install

​Configure

​Wire the client, once

​Guard a paid route

​When the cost is not known upfront

​Free endpoints that still need a caller

​Three things that cost money quietly

​What we verified

​If you would rather not take a dependency

Install

Configure

Wire the client, once

Guard a paid route

When the cost is not known upfront

Free endpoints that still need a caller

Three things that cost money quietly

What we verified

If you would rather not take a dependency