README

Wolt Drive carrier adapter for shubo/module-shipping-core.

Status: scaffold (Phase 7, 2026-04-21). Sandbox adapter only — live merchant credentials require a paid Wolt Drive account and are outside the scope of this release.

What this module is

A concrete implementation of Shubo\ShippingCore\Api\CarrierGatewayInterface and Shubo\ShippingCore\Api\WebhookHandlerInterface for Wolt Drive — Wolt's business-to-consumer on-demand delivery service. Core orchestrates; this adapter translates.

What it is NOT

Not a fork of Wolt's SDK. We call the public REST API directly via Magento's CurlFactory so the module stays small and auditable.
Not merchant-account automation. You need a real Wolt Drive merchant account (sandbox free, prod paid).
Not a multi-parcel integration. Wolt Drive treats each delivery as a single parcel.

Capability declaration

Capability	Supported	Notes
Webhooks	✓	HMAC-SHA256 signed. See `WoltDriveWebhookHandler`.
Sandbox	✓	`https://daas-public-api.development.dev.woltapi.com/`
COD reconciliation API	✗	Cash reconciliation is offline via weekly invoice.
PUDO	✗	Door-to-door only.
Express	✓	Wolt Drive's core value proposition.
Multi-parcel	✗	Single parcel per delivery order.
Returns	✓	Supported via `cancelShipment`.
Cancel after pickup	✓	Up until `dropoff_enroute`.

Installation

composer require shubo/module-shipping-wolt-drive
bin/magento module:enable Shubo_ShippingWoltDrive
bin/magento setup:upgrade

Configuration

Per-merchant (scoped to the Magento website/store), admin-only:

Config path	Meaning
`shipping/wolt_drive/merchant_api_key`	Encrypted. Wolt's Merchant API bearer key.
`shipping/wolt_drive/venue_id`	Wolt-assigned venue identifier.
`shipping/wolt_drive/is_sandbox`	1 = use sandbox base URL; 0 = prod.
`shipping/wolt_drive/webhook_secret`	Encrypted. HMAC secret for webhook verification.

A future release ships a system.xml to expose these in the admin UI; for now, set them via CLI:

bin/magento config:set --scope=websites --scope-code=m_tbilvino \
  shipping/wolt_drive/is_sandbox 1
bin/magento config:set --scope=websites --scope-code=m_tbilvino \
  shipping/wolt_drive/venue_id VEN-12345
# secrets (encrypted) must be set via the admin UI or:
bin/magento config:sensitive:set --scope=websites --scope-code=m_tbilvino \
  shipping/wolt_drive/merchant_api_key <KEY>

Webhook endpoint

Core's frontend route POST /shubo_shipping/webhook/wolt_drive receives webhook deliveries. Wolt Drive signs requests with:

X-Wolt-Signature — base64-encoded HMAC-SHA256 of timestamp.body using the shared secret.
X-Wolt-Timestamp — Unix epoch seconds.

Invalid signatures, replays (>5min clock skew), and malformed bodies are rejected with WebhookResult::STATUS_REJECTED. Accepted webhooks flow through Core's dispatcher, which writes the shipment event + updates shipment status.

Status vocabulary map

Wolt Drive → Core ShipmentInterface::STATUS_*:

Wolt status	Core status
`created`, `accepted`, `pickup_enroute`, `pickup_arrived`	`READY_FOR_PICKUP`
`picked_up`	`PICKED_UP`
`dropoff_enroute`, `dropoff_arrived`	`OUT_FOR_DELIVERY`
`delivered`	`DELIVERED`
`cancelled`	`CANCELLED`
`failed`	`FAILED`

Testing

composer install
vendor/bin/phpunit
vendor/bin/phpstan analyse --level=8
vendor/bin/phpcs --standard=Magento2 --extensions=php Model

Unit tests mock the HTTP client and inject synthetic webhook signatures — no live Wolt API calls. Integration tests against the Wolt sandbox require merchant credentials and are deferred to a follow-up release.

License

Apache-2.0 — matches shubo/module-shipping-core, shubo/module-tbc-payment, and shubo/module-bog-payment.

shubo / module-shipping-wolt-drive

Maintainers

Package info

Statistics

Security