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

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

• Integration Guide
• API Reference
• Errors
• Contributing
• Security
• Changelog

Examples

• canonical-flow.php
• create-creator.php
• create-link.php
• issue-iit.php
• lock-pit.php
• record-paid-order.php
• record-refund.php
• list-orders.php
• get-order-details.php

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 Contact

• Website: https://qredex.com
• X: https://x.com/qredex
• Email: os@qredex.com