README

PHP SDK for invoq server APIs and webhook verification.

Use this package only on your server. It accepts secret keys and must not be bundled into browser code.

Installation

composer require invoq/invoq-php

Requires PHP 8.1 or newer.

Create a client

<?php

use Invoq\Invoq;

$invoq = new Invoq($_ENV['INVOQ_SECRET_KEY']);

Production API default:

https://api.invoq.money

Override the API origin during development:

$invoq = new Invoq($_ENV['INVOQ_SECRET_KEY'], [
    'apiBaseUrl' => 'http://localhost:8787',
]);

apiBaseUrl must be an absolute http or https URL without username, password, query, or hash parts. Pass the API origin; the SDK appends /v1/... resource paths. A trailing /v1 is accepted and normalized away.

Create an invoice

$invoice = $invoq->invoices->create([
    'amount' => '149',
    'currency' => 'USD',
    'description' => 'SaaS boilerplate',
    'reference_id' => 'order_1234',
]);

Use a stable reference_id to map the invoq invoice back to your order during webhook fulfillment.

description and reference_id are optional request strings. Omit them when unset; do not pass null.

The SDK returns the response data object directly as an associative array.

Get an invoice

$invoice = $invoq->invoices->get('inv_123');

The SDK returns the response data object directly as an associative array.

Create a test payment

$paidInvoice = $invoq->invoices->createTestPayment($invoice['id'], [
    'amount' => '149',
    'reference_id' => 'test_payment_001',
]);

This endpoint requires a test secret key.

reference_id is an optional request string. Omit it when unset; do not pass null.

The SDK returns the response data object directly as an associative array.

Verify webhooks

Pass the raw request body to verifyWebhook. Do not parse JSON and encode it again before verification.

<?php

use function Invoq\isInvoicePaid;
use function Invoq\verifyWebhook;

$rawBody = file_get_contents('php://input');
$event = verifyWebhook(
    $rawBody === false ? '' : $rawBody,
    ['invoq-signature' => $_SERVER['HTTP_INVOQ_SIGNATURE'] ?? null],
    $_ENV['INVOQ_WEBHOOK_SECRET'],
);

if (isInvoicePaid($event)) {
    $orderId = $event['data']['invoice']['reference_id'];

    if ($orderId === null) {
        throw new RuntimeException('Missing invoice reference_id for fulfillment.');
    }

    fulfillOrder($orderId);
}

http_response_code(200);

Webhook verification failures throw InvoqSignatureVerificationError. verifyWebhook returns the decoded webhook event as an associative array.

verifyWebhook does not require new Invoq(...) or your invoq API secret key. Use your webhook secret, not INVOQ_SECRET_KEY.

Fulfill orders from verified webhooks, not browser checkout results.

Error handling

<?php

use Invoq\InvoqApiError;
use Invoq\InvoqError;

try {
    $invoq->invoices->create(['amount' => '', 'currency' => 'USD']);
} catch (InvoqApiError $error) {
    error_log((string) $error->status);
    error_log((string) $error->getApiCode());
    error_log(json_encode($error->fields));
    error_log(json_encode($error->meta));
} catch (InvoqError $error) {
    throw $error;
}

Connection and response parse failures throw InvoqError.

Use $error->getApiCode() for invoq API error codes. PHP's built-in $error->getCode() returns the exception code, not the API error code.

Webhook verification failures throw InvoqSignatureVerificationError with one of these codes:

missing_signature
invalid_signature_header
timestamp_outside_tolerance
signature_mismatch
invalid_payload

Read it with $error->getSignatureCode().

Development

composer validate --strict
composer dump-autoload
composer test