regna/urbaniqo-sdk

Official PHP SDK for the Urbaniqo Transit protocol — sell your tickets, passes and subscriptions through the Urbaniqo app.

v1.0.1 2026-05-04 17:37 UTC

Requires

• php: ^8.2
• ext-hash: *
• ext-json: *
• psr/http-client: ^1.0
• psr/http-factory: ^1.0
• psr/http-message: ^1.1 || ^2.0

Requires (Dev)

• guzzlehttp/guzzle: ^7.8
• guzzlehttp/psr7: ^2.6
• phpunit/phpunit: ^10.5 || ^11.0

Suggests

• guzzlehttp/guzzle: Default PSR-18 implementation; pass it to UrbaniqoClient if you don't already have one.

MIT

• sdk
• transport
• transit
• ticketing
• urbaniqo

README

Official PHP client for Urbaniqo Transit — the channel that lets your customers buy your tickets, passes and subscriptions through the Urbaniqo app.

Looking for the JavaScript / Node SDK? It lives in a separate repository: regnatech/urbaniqo-sdk-js.

Package	Manager	Status
regna/urbaniqo-sdk	Composer · PHP ≥ 8.2	v1

Wire-level spec for both SDKs: docs/protocol.md.

Install

composer require regna/urbaniqo-sdk guzzlehttp/guzzle

guzzlehttp/guzzle is the recommended PSR-18 implementation. Bring your own if you already have a different one.

Quick start

use GuzzleHttp\Client as Guzzle;
use GuzzleHttp\Psr7\HttpFactory;
use Regna\UrbaniqoSdk\Client;

$factory = new HttpFactory();
$urbaniqo = new Client(
    agencyId:       $_ENV['URBANIQO_AGENCY_ID'],
    keyId:          $_ENV['URBANIQO_KEY_ID'],
    secret:         $_ENV['URBANIQO_SECRET'],
    httpClient:     new Guzzle(),
    requestFactory: $factory,
    streamFactory:  $factory,
    // baseUrl defaults to https://urbaniqo.com/api/transit/v1
);

$urbaniqo->upsertTariffs([
    [
        'id' => 'AMT-110',
        'name' => ['en' => 'Single ride 110\'', 'it' => 'Corsa singola 110 minuti'],
        'kind' => 'single_ride',
        'fare_cents' => 200,
        'currency' => 'EUR',
        'default_validity_seconds' => 110 * 60,
        'is_active' => true,
    ],
]);

What the SDK gives you

• HMAC-SHA256 request signing (Authorization header in canonical-request form)
• Idempotent retries with exponential backoff for safe verbs (PUT, GET, idempotent POSTs)
• Webhooks\Verifier for inbound webhook signature checking — pass the raw request body
• Typed exceptions: UrbaniqoApiException, UrbaniqoTransportException, UrbaniqoWebhookException

Webhook handler (Laravel example)

A complete drop-in lives at examples/php-laravel-webhook/routes-snippet.php.

Docs

• docs/protocol.md — wire-level spec
• docs/getting-started.md — onboarding walkthrough
• docs/webhooks.md — webhook events + payload shapes
• docs/error-codes.md — full error code reference
• docs/barcode-formats.md — supported ticket formats
• docs/changelog.md

License

MIT — see LICENSE.