Download the PHP package zerokyc/zkp-sdk-php without Composer
On this page you can find all versions of the php package zerokyc/zkp-sdk-php. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Informations about the package zkp-sdk-php
zkp-sdk-php
Official PHP SDK for the ZeroKYC Pay crypto payment gateway. Framework-agnostic, no third-party runtime dependencies (requires the PHP JSON and cURL extensions), PHP 8.1+.
WHMCS, WooCommerce, Blesta, Paymenter, FOSSBilling and OpenCart adapters for ZeroKYC are built on this package - if you integrate anything else, build it here too: API client, webhook verification, idempotency and status mapping are done for you.
Install
(If the package is not on Packagist yet, use the VCS repository:
)
Quickstart (sandbox invoice in 5 minutes)
- Create an account at console.zerokyc-payments.com
and copy a sandbox API key (
pk_test_...) from API keys. -
Create an invoice and send the buyer to the hosted checkout:
- Get paid: ZeroKYC detects the on-chain payment and POSTs a signed webhook
to your endpoint. A verified webhook (or a server-side
getInvoice()) is the only proof of payment - never a browser success URL.
Full production flow with duplicate protection and payment matching: examples/safe-webhook-handler.php.
Configuration
| Key | Required | Notes |
|---|---|---|
api_key |
yes | pk_test_... sandbox / pk_live_... production |
environment |
no | sandbox | production; inferred from the key; mismatch throws |
webhook_secret |
for webhooks | whsec_... from console → Webhooks |
timeout |
no | per-request HTTP timeout, seconds (default 15) |
max_retries |
no | bounded retries, 0-5 (default 2) |
base_url |
tests only | overrides the central API base URL |
The API base URL is defined centrally by the SDK. Never hard-code URLs in platform adapters.
Status normalization
Raw API statuses never leak into your billing logic:
| API (raw) | SDK enum |
|---|---|
created, pending |
InvoiceStatus::PENDING |
detecting (seen, awaiting confs) |
InvoiceStatus::CONFIRMING |
confirmed |
InvoiceStatus::PAID |
underpaid |
InvoiceStatus::UNDERPAID |
expired |
InvoiceStatus::EXPIRED |
canceled |
InvoiceStatus::CANCELLED |
| unknown | InvoiceStatus::FAILED (alert) |
$invoice->isPaid() / $invoice->isTerminal() answer the common questions.
Idempotency
Always pass a stable idempotency key when creating invoices from an order:
A timeout + retry then returns the same invoice
(CreateInvoiceResponse::idempotentReplay === true) instead of a duplicate.
Error handling & retries
| Exception | HTTP | Retried automatically? |
|---|---|---|
AuthenticationException |
401 / 403 | never |
ValidationException |
400 / 422 | never |
RateLimitException |
429 | yes (honors Retry-After up to 5s, max twice) |
ApiException |
5xx, 402, 404… | only GET / idempotent POST |
NetworkException |
timeout/DNS | only GET / idempotent POST |
WebhookVerificationException |
n/a | n/a (reason code on $e->reason) |
Backoff is bounded exponential (300ms → 600ms → 1200ms, capped by max_retries).
Webhook security checklist
- verify against the exact raw body (never
json_encode(json_decode(...))); t=/v1=header format, lowercase hex, constant-time compare (built in);- default ±300 s timestamp window (
new WebhookVerifier($secret, 600)to widen); - treat delivery as at-least-once: deduplicate with
ReplayGuard+EventStoreInterfacebacked by your database; - match invoice id / amount / asset against the local order before activating
(
ReplayGuard::matchesOrder()); - never log API keys or webhook secrets (the SDK never puts them in exceptions).
Self-test against the documented vector:
Assets
USDT on seven networks (TRC-20, Polygon, BEP-20 on BSC, ERC-20 on Ethereum, Arbitrum, Solana SPL, TON jetton), USDC/USDT (Polygon, Arbitrum, Solana), native ETH, native BNB, native TRX, LTC, DOGE, BCH, XRP, NEAR, BTC, XMR and native TON. Pass an
asset id as payment_currency to pin one (USDT_TRON), or any (default) to
let the buyer choose at checkout.
Tests
License
MIT — see LICENSE.
All versions of zkp-sdk-php with dependencies
ext-json Version *
ext-curl Version *