shieldz/shieldz

Official PHP SDK for Shieldz — non-custodial crypto payments with $0 fees.

Accept USDC/USDT across Base, Arbitrum, Optimism, Polygon, and Ethereum, plus native Bitcoin and shielded Zcash. Funds settle straight to your own wallet — Shieldz never holds them, and never asks for your keys.

Install

composer require shieldz/shieldz

Requires PHP 8.0+ with the curl and json extensions. No other dependencies.

Quickstart

use Shieldz\Shieldz;

$shieldz = new Shieldz(getenv('SHIELDZ_API_KEY'));

$invoice = $shieldz->invoices->create([
    'amount_usd_cents' => 5000,        // $50.00
    'memo' => 'Order #1234',
    'metadata' => ['order_id' => '1234'],
]);

echo $invoice['pay_url']; // send your customer to the hosted checkout

Retrieve, list & auto-paginate

$inv = $shieldz->invoices->retrieve('Qgvz8WQw0mnv2M8');

$page = $shieldz->invoices->list(['limit' => 20, 'status' => 'paid']);

foreach ($shieldz->invoices->listAll(['status' => 'paid']) as $invoice) {
    echo $invoice['id'], "\n";
}

Retryable POSTs get an auto idempotency_key so a retried create can't duplicate; pass your own to tie it to an order.

Products, prices & payment links

Sell from a catalog, the way Stripe does: prices live in Shieldz, so a buyer's browser can never change what they pay.

$hoodie = $shieldz->products->create([
    'name' => 'Blue hoodie',
    'default_price_data' => ['unit_amount_usd_cents' => 4999],
]);

// A hosted page ($link['url']) and the target of the widget's buy button:
//   <button data-shieldz-link="plink_…">Buy now</button>
$link = $shieldz->paymentLinks->create([
    'line_items' => [['product' => $hoodie['id'], 'adjustable_quantity' => ['enabled' => true, 'maximum' => 5]]],
    'collect_shipping_address' => true,
]);

// Or price an order on your server:
$invoice = $shieldz->invoices->create([
    'line_items' => [
        ['price' => $hoodie['default_price']['id'], 'quantity' => 2],
        ['price_data' => ['name' => 'Gift wrap', 'unit_amount_usd_cents' => 300]],
    ],
    'client_reference_id' => 'A-1043',
]);

Paid invoices carry line_items, payment_link, client_reference_id and, when the link asked for it, shipping.

Products and payment links have no test mode: a link takes real payments whichever key made it. To try a priced checkout without real money, create an invoice with line_items and an sk_test_ key. A checkout's total must be from $1 to $100,000. The full walkthrough is in examples/catalog.php.

Webhooks

Verify against the raw request body:

use Shieldz\Webhooks;
use Shieldz\SignatureVerificationError;

$raw = file_get_contents('php://input');
$sig = $_SERVER['HTTP_X_SHIELDZ_SIGNATURE'] ?? '';

try {
    $event = Webhooks::constructEvent($raw, $sig, getenv('SHIELDZ_WEBHOOK_SECRET'));
} catch (SignatureVerificationError $e) {
    http_response_code(400);
    exit;
}

if ($event['type'] === 'invoice.paid') {
    // fulfill — dedupe on the X-Shieldz-Delivery header (at-least-once)
}
http_response_code(200);

Webhooks::verifySignature(...) returns a bool / throws if you just want the check. During the 24h after a secret rotation the header carries both signatures and either matches.

Errors

Any non-2xx throws Shieldz\ShieldzError with ->status, ->type, ->errorCode, ->param, ->requestId (the machine code is ->errorCode because \Exception reserves the integer ->code, which we set to the HTTP status).

Links

• Docs / API quickstart: https://shieldz.cash/docs
• Is it safe? (non-custodial proof): https://shieldz.cash/verify
• Node SDK: https://github.com/ShieldZCash/shieldz-sdk · Python: https://github.com/ShieldZCash/shieldz-python · Rust: https://github.com/ShieldZCash/shieldz-rust

License

MIT © Deniz Yanbollu / Shieldz