README

Qredex PHP SDK

Canonical PHP server SDK for the Qredex Integrations API.

This package is for machine-to-machine integrations only. It is designed to make the canonical backend flow easy and safe:

create link -> issue IIT -> lock PIT -> record paid order -> record refund

It does not include Merchant API endpoints, browser/runtime logic, Shopify embedded flows, or webhook receivers.

Installation

composer require qredex/php

Ota Workflow

Use Ota for repo work, validation, and release prep:

ota run setup
ota run analyse
ota run test
ota run test:live
ota run version:bump --version minor
ota run ci

Support Matrix

Area	Supported
PHP runtime	`8.2+`
Composer	`2.x`
Default CI	`composer validate --strict`, `composer test`, `composer analyse`
Live tests	Manual-only `composer test:live` or GitHub `workflow_dispatch`
Release flow	`ota run version:bump --version major

Requirements

PHP 8.2 or newer
Composer 2
Machine-to-machine Qredex Integrations API credentials

Quick Start

<?php

use Qredex\Config\QredexConfig;
use Qredex\Qredex;
use Qredex\Auth\QredexScope;
use Qredex\Request\CreateLinkRequest;
use Qredex\Request\IssueInfluenceIntentTokenRequest;
use Qredex\Request\LockPurchaseIntentRequest;
use Qredex\Request\RecordPaidOrderRequest;
use Qredex\Request\RecordRefundRequest;

$qredex = Qredex::init(QredexConfig::fromEnvironment(
    scope: [
        QredexScope::LINKS_WRITE,
        QredexScope::INTENTS_WRITE,
        QredexScope::ORDERS_WRITE,
    ],
));

$link = $qredex->links()->create(new CreateLinkRequest(
    storeId: '61abc354-dd8d-4a23-be02-ece77b1b4da6',
    creatorId: '16fca3f2-b346-4f98-8e52-0895aac61c5b',
    linkName: 'spring-launch',
    destinationPath: '/products/spring-launch',
    attributionWindowDays: 30,
));

$iit = $qredex->intents()->issueInfluenceIntentToken(new IssueInfluenceIntentTokenRequest(
    linkId: $link->id,
    landingPath: '/products/spring-launch',
));

$pit = $qredex->intents()->lockPurchaseIntent(new LockPurchaseIntentRequest(
    token: $iit->token,
    source: 'backend-cart',
));

$order = $qredex->orders()->recordPaidOrder(new RecordPaidOrderRequest(
    storeId: $link->storeId,
    externalOrderId: 'order-100045',
    currency: 'USD',
    orderNumber: '100045',
    totalPrice: 110.00,
    purchaseIntentToken: $pit->token,
));

$refund = $qredex->refunds()->recordRefund(new RecordRefundRequest(
    storeId: $link->storeId,
    externalOrderId: 'order-100045',
    externalRefundId: 'refund-100045-1',
    refundTotal: 25.00,
));

Initialization

Preferred typed initialization:

<?php

use Qredex\Config\QredexConfig;
use Qredex\Qredex;
use Qredex\Auth\QredexScope;

$qredex = Qredex::init(QredexConfig::fromEnvironment(
    scope: [
        QredexScope::LINKS_WRITE,
        QredexScope::INTENTS_WRITE,
        QredexScope::ORDERS_WRITE,
    ],
    timeoutMs: 15_000,
    requestIdHeader: 'x-client-request-id',
    requestIdFactory: static fn (): string => bin2hex(random_bytes(16)),
));

Required environment variables:

QREDEX_CLIENT_ID
QREDEX_CLIENT_SECRET

Optional environment variables:

QREDEX_SCOPE
QREDEX_ENVIRONMENT
QREDEX_BASE_URL
QREDEX_TIMEOUT_MS

Programmatic configuration should prefer QredexScope values over raw scope strings.

Qredex::bootstrap() remains available as the convenience path for environment-only initialization, while QredexConfig::fromEnvironment() is the recommended typed option for any customization.

Stability

The canonical typed write flow is the primary stable public surface.
Legacy array payloads remain supported for backward compatibility only and should not be treated as the primary public contract.
The public surface is intentionally limited to Integrations API resource operations and automatic client-credentials auth.

Public API

Stable canonical write surface:

$qredex->creators()->create(...);
$qredex->links()->create(...);
$qredex->intents()->issueInfluenceIntentToken(...);
$qredex->intents()->lockPurchaseIntent(...);
$qredex->orders()->recordPaidOrder(...);
$qredex->refunds()->recordRefund(...);

Operational read surface:

$qredex->creators()->get($creatorId);
$qredex->creators()->list([...]);
$qredex->links()->get($linkId);
$qredex->links()->list([...]);
$qredex->links()->getStats($linkId);
$qredex->orders()->list([...]);
$qredex->orders()->getDetails($orderAttributionId);

Errors

The SDK separates local validation, API validation, and protocol/response failures:

Qredex\Error\RequestValidationError
Qredex\Error\ApiValidationError
Qredex\Error\ResponseDecodingError
Qredex\Error\AuthenticationError
Qredex\Error\AuthorizationError
Qredex\Error\NotFoundError
Qredex\Error\ConflictError
Qredex\Error\RateLimitError
Qredex\Error\ApiError
Qredex\Error\NetworkError
Qredex\Error\ConfigurationError

Operational Defaults

OAuth tokens are issued automatically and cached until close to expiry.
Writes are never retried automatically.
Read retries are opt-in and honor Retry-After when provided.
Client-side correlation ids can be emitted and optionally attached to outgoing headers.
The SDK does not log client secrets, bearer tokens, IITs, or PITs by default.

Releases

Releases are semantic-version Git tags such as v0.2.0.
GitHub Actions validates tagged releases, creates a GitHub Release, and can optionally notify Packagist through PACKAGIST_WEBHOOK_URL.
Composer consumers should install tagged releases from Packagist or the GitHub repository source configured in Composer.

Docs

Examples

Testing

composer test runs unit and mocked transport tests only
composer test:live runs the opt-in live integration suite
Live tests exercise the canonical integrations flow against a real API and are intentionally excluded from default CI and release checks.

Live tests are skipped unless QREDEX_LIVE_ENABLED=1 and the required QREDEX_LIVE_* variables are set.

Start from .env.live.example when wiring live test credentials.

Release Notes

Releasing

qredex / php

Maintainers

Package info

Statistics

Security