Montonio PHP SDK

PHP SDK for the Montonio Stargate API and Shipping V2 API. Wraps both APIs with fluent struct builders and JWT-authenticated requests.

Features

• Full API coverage — Payments (Stargate) and Shipping V2 APIs
• PSR-18 support — bring your own HTTP client (Guzzle, Symfony, etc.) or use the built-in cURL transport
• Fluent struct builders — build request payloads with chained setters, array hydration, or static create() with named parameters
• Typed enums — Environment, PaymentMethod, PaymentStatus backed enums with full IDE support
• Granular exceptions — AuthenticationException, ValidationException, NotFoundException, RateLimitException, ServerException
• JWT authentication — token generation, webhook signature verification

API Coverage

Client	Methods	API Docs
Orders	createOrder, getOrder	Orders guide
Payment Links	createPaymentLink, getPaymentLink	Payment links guide
Payment Intents	createDraft	Embedded cards guide
Refunds	createRefund	Refunds guide
Sessions	createSession	Embedded cards guide
Payouts	getPayouts, exportPayout, getBalances	Payouts guide
Stores	getPaymentMethods	Payment methods guide
Shipping / Carriers	getCarriers	Shipping API reference
Shipping / Methods	getShippingMethods, getPickupPoints, getCourierServices, filterByParcels, getRates	Shipping methods guide
Shipping / Shipments	createShipment, updateShipment, getShipment	Shipments guide
Shipping / Labels	createLabelFile, getLabelFile	Labels guide
Shipping / Webhooks	createWebhook, listWebhooks, deleteWebhook	Webhooks guide

Supported payment methods: bank payments, card payments (Apple Pay, Google Pay), BLIK, Buy Now Pay Later, and Hire Purchase.

Requirements

• PHP 8.2 or later
• cURL extension (or a PSR-18 HTTP client)

Using PHP 8.0 or 8.1? v1 (1.x branch) is actively maintained with full API coverage (Payments + Shipping):

composer require makstech/montonio-php-sdk:^1.0

Upgrading from v1? See the upgrade guide — most users need no code changes.

Installation

composer require makstech/montonio-php-sdk

Getting Started

Get your API keys from the Montonio Partner System (Stores → your store → API keys).

use Montonio\MontonioClient;

$client = new MontonioClient(
    $accessKey,
    $secretKey,
    MontonioClient::ENVIRONMENT_SANDBOX, // or ENVIRONMENT_LIVE
);

All sub-clients are accessed via factory methods on the main client (e.g. $client->orders(), $client->refunds()).

Custom HTTP Client (PSR-18)

By default, the SDK uses cURL for HTTP requests. You can optionally provide your own PSR-18 HTTP client:

use Montonio\MontonioClient;

$httpFactory = new \Nyholm\Psr7\Factory\Psr17Factory();

$client = new MontonioClient(
    $accessKey,
    $secretKey,
    MontonioClient::ENVIRONMENT_SANDBOX,
    httpClient: new \GuzzleHttp\Client(),
    requestFactory: $httpFactory,
    streamFactory: $httpFactory,
);

This is useful for testing (inject a mock client) or when your framework already provides an HTTP client.

Orders

Create a payment order and redirect the customer to the payment URL.

Structs can be built fluently or from arrays — both approaches can be mixed:

$orderData = (new \Montonio\Structs\OrderData())
    ->setMerchantReference('ORDER-123')
    ->setReturnUrl('https://myshop.com/return')
    ->setNotificationUrl('https://myshop.com/webhook')
    ->setGrandTotal(29.99)
    ->setCurrency('EUR')
    ->setLocale('en')
    ->setPayment(
        (new \Montonio\Structs\Payment())
            ->setMethod(\Montonio\Structs\Payment::METHOD_PAYMENT_INITIATION)
            ->setAmount(29.99)
            ->setCurrency('EUR')
    )
    ->setLineItems([
        [
            'name' => 'T-Shirt',
            'quantity' => 1,
            'finalPrice' => 19.99,
        ],
    ])
    ->addLineItem(
        (new \Montonio\Structs\LineItem())
            ->setName('Socks')
            ->setQuantity(2)
            ->setFinalPrice(5.00)
    )
    ->setBillingAddress(new \Montonio\Structs\Address([
        'firstName' => 'John',
        'lastName' => 'Doe',
        'email' => 'john@example.com',
        'addressLine1' => 'Main St 1',
        'locality' => 'Tallinn',
        'country' => 'EE',
    ]));

$order = $client->orders()->createOrder($orderData);

// Redirect customer to payment
header('Location: ' . $order['paymentUrl']);

Retrieve an order:

$order = $client->orders()->getOrder($orderUuid);
echo $order['paymentStatus']; // 'PAID', 'PENDING', etc.

See the orders guide for all available fields and response details.

Payment Methods

Fetch available payment methods for your store:

$methods = $client->stores()->getPaymentMethods();

Payment Links

Create shareable payment links without building a full checkout:

$link = $client->paymentLinks()->createPaymentLink(
    (new \Montonio\Structs\CreatePaymentLinkData())
        ->setDescription('Invoice #456')
        ->setCurrency('EUR')
        ->setAmount(50.00)
        ->setLocale('en')
        ->setAskAdditionalInfo(true)
        ->setExpiresAt(date('c', strtotime('+7 days')))
        ->setType('one_time')
        ->setNotificationUrl('https://myshop.com/webhook')
);

echo $link['url']; // https://pay.montonio.com/...

Retrieve a payment link:

$link = $client->paymentLinks()->getPaymentLink($linkUuid);

Refunds

Issue a full or partial refund for a paid order:

$refund = $client->refunds()->createRefund(
    (new \Montonio\Structs\CreateRefundData())
        ->setOrderUuid($orderUuid)
        ->setAmount(10.00)
        ->setIdempotencyKey($uniqueKey) // V4 UUID recommended
);

echo $refund['status']; // 'PENDING'

Webhooks

Montonio sends webhook notifications to your notificationUrl when order or refund statuses change. Use decodeToken() to verify the JWT signature and decode the payload:

// Order webhook: {"orderToken": "<jwt>"}
$decoded = $client->decodeToken($requestBody['orderToken']);
echo $decoded->paymentStatus; // 'PAID', 'PENDING', 'ABANDONED', etc.
echo $decoded->merchantReference;

// Refund webhook: {"refundToken": "<jwt>"}
$decoded = $client->decodeToken($requestBody['refundToken']);
echo $decoded->refundStatus; // 'SUCCESSFUL', 'PENDING', 'REJECTED', etc.

See the webhooks guide for full payload details and retry policy.

Embedded Payments

Embedded Card Payments

For embedding card payment fields directly in your checkout, create a session and pass it to the MontonioCheckout JS SDK:

$session = $client->sessions()->createSession();
$sessionUuid = $session['uuid']; // Pass to frontend JS SDK

Embedded BLIK

For embedded BLIK payments, pass the customer's 6-digit BLIK code when creating an order:

$orderData = (new \Montonio\Structs\OrderData())
    ->setPayment(
        (new \Montonio\Structs\Payment())
            ->setMethod(\Montonio\Structs\Payment::METHOD_BLIK)
            ->setAmount(100.00)
            ->setCurrency('PLN')
            ->setMethodOptions(
                (new \Montonio\Structs\PaymentMethodOptions())
                    ->setBlikCode('777123')
            )
    )
    // ... other order fields
;

See the embedded BLIK guide for the full flow.

Payouts

Retrieve payout reports and balances:

// Get store balances
$balances = $client->payouts()->getBalances();

// List payouts for a store
$payouts = $client->payouts()->getPayouts($storeUuid, limit: 50, offset: 0, order: 'DESC');

// Export a payout report (excel or xml)
$export = $client->payouts()->exportPayout($storeUuid, $payoutUuid, 'excel');
$downloadUrl = $export['url'];

Shipping

All shipping sub-clients are accessed via $client->shipping():

Carriers

$carriers = $client->shipping()->carriers()->getCarriers();

Shipping Methods

// All shipping methods
$methods = $client->shipping()->shippingMethods()->getShippingMethods();

// Pickup points for a carrier
$pickupPoints = $client->shipping()->shippingMethods()
    ->getPickupPoints('omniva', 'EE');

// Courier services for a carrier
$courierServices = $client->shipping()->shippingMethods()
    ->getCourierServices('dpd', 'EE');

// Filter methods by parcel dimensions
$filtered = $client->shipping()->shippingMethods()->filterByParcels(
    (new \Montonio\Structs\Shipping\FilterByParcelsData())
        ->setParcels([
            (new \Montonio\Structs\Shipping\ShipmentParcel())->setWeight(1.5),
        ]),
    'EE' // destination
);

// Calculate shipping rates
$rates = $client->shipping()->shippingMethods()->getRates(
    (new \Montonio\Structs\Shipping\ShippingRatesData())
        ->setDestination('EE')
        ->setParcels([
            (new \Montonio\Structs\Shipping\RatesParcel())->setItems([
                (new \Montonio\Structs\Shipping\RatesItem())
                    ->setLength(20.0)
                    ->setWidth(15.0)
                    ->setHeight(10.0)
                    ->setWeight(0.5),
            ]),
        ])
);

Shipments

$shipment = $client->shipping()->shipments()->createShipment(
    (new \Montonio\Structs\Shipping\CreateShipmentData())
        ->setShippingMethod(
            (new \Montonio\Structs\Shipping\ShipmentShippingMethod())
                ->setType('pickupPoint')
                ->setId($pickupPointId) // UUID from getPickupPoints()
        )
        ->setReceiver(
            (new \Montonio\Structs\Shipping\ShippingContact())
                ->setName('John Doe')
                ->setPhoneCountryCode('372')
                ->setPhoneNumber('53334770')
                ->setEmail('john@example.com')
        )
        ->setParcels([
            (new \Montonio\Structs\Shipping\ShipmentParcel())->setWeight(1.0),
        ])
        ->setMerchantReference('ORDER-123')
);

echo $shipment['id'];
echo $shipment['status']; // 'pending', 'registered', etc.

// Get shipment details
$shipment = $client->shipping()->shipments()->getShipment($shipmentId);

// Update a shipment
$updated = $client->shipping()->shipments()->updateShipment($shipmentId,
    (new \Montonio\Structs\Shipping\UpdateShipmentData())
        ->setReceiver(
            (new \Montonio\Structs\Shipping\ShippingContact())
                ->setName('Jane Doe')
                ->setPhoneCountryCode('372')
                ->setPhoneNumber('55512345')
        )
);

Label Files

$labelFile = $client->shipping()->labels()->createLabelFile(
    (new \Montonio\Structs\Shipping\CreateLabelFileData())
        ->setShipmentIds([$shipmentId])
        ->setPageSize('A4')
        ->setSynchronous(true)
);

echo $labelFile['labelFileUrl']; // PDF download URL (expires in 5 minutes)

// Get label file status
$labelFile = $client->shipping()->labels()->getLabelFile($labelFileId);
echo $labelFile['status']; // 'pending', 'ready', 'failed'

Shipping Webhooks

$webhook = $client->shipping()->webhooks()->createWebhook(
    (new \Montonio\Structs\Shipping\CreateShippingWebhookData())
        ->setUrl('https://myshop.com/shipping-webhook')
        ->setEnabledEvents([
            'shipment.registered',
            'shipment.statusUpdated',
            'labelFile.ready',
        ])
);

// List all webhooks
$webhooks = $client->shipping()->webhooks()->listWebhooks();

// Delete a webhook
$client->shipping()->webhooks()->deleteWebhook($webhookId);

See the Shipping API reference for all available fields and response details.

License

This library is made available under the MIT License (MIT). Please see License File for more information.