Integration example

💡

Looking for a working reference?

The seQura demo shop is a fully functional example built on top of the integration-core library. Its source code is available at github.com/sequra/demo-shop.

The sequra/integration-core Composer package provides a PHP framework for integrating seQura into any e-commerce platform. It handles the API communication, order lifecycle, and webhook processing—so you only need to implement the platform-specific pieces: persistence, configuration, and business logic adapters.

This page walks through each required piece in the order you should implement it.

Prerequisites

• PHP >= 7.2 (8.x recommended), with json, ctype, and mbstring extensions
• Composer
• seQura merchant credentials (SEQURA_ACCOUNT_KEY, SEQURA_ACCOUNT_SECRET)
• A publicly accessible URL for receiving webhooks

Step 1 — Install the library

composer require sequra/integration-core

Step 2 — Implement core infrastructure services

These three services are mandatory. The library cannot function without them.

Configuration service

Extend SeQura\Core\Infrastructure\Configuration\Configuration and implement:

• getIntegrationName() — a string identifying your platform (e.g. "WooCommerce")
• getAsyncProcessUrl($guid) — URL for async task processing (return "" if unused)
• saveConfigValue($name, $value) — persist a key-value pair in your storage
• getConfigValue($name, $default) — retrieve a stored value

Logger service

Implement SeQura\Core\Infrastructure\Logger\Interfaces\ShopLoggerAdapter. Route logMessage(LogData $data) to your platform's logging system. $data->getLogLevel() returns 0=ERROR, 1=WARNING, 2=INFO, 3=DEBUG.

Encryptor service

Implement SeQura\Core\BusinessLogic\Utility\EncryptorInterface with encrypt(string $data): string and decrypt(string $encryptedData): string. Used to protect stored API credentials.

Step 3 — Implement platform services

Store integration service

Implement StoreIntegrationServiceInterface to provide your webhook URL and the capabilities your integration supports:

public function getWebhookUrl(): URL
{
    return new URL('https://myshop.com/sequra/webhook');
}

public function getSupportedCapabilities(): array
{
    return [
        Capability::general(),
        Capability::widget(),
        Capability::orderStatus(),
    ];
}

Shop order statuses service

Implement ShopOrderStatusesServiceInterface::getShopOrderStatuses() to return the list of order statuses in your platform. The seQura admin UI uses this list to let merchants map seQura states to platform states.

Step 4 — Implement order management services

Merchant data provider

Implement MerchantDataProviderInterface to supply the callback URLs and options used throughout the seQura checkout flow:

Order creation service

Implement OrderCreationInterface::createOrder(string $cartId): string. This is called when seQura approves a payment—convert the cart to a confirmed order and return your platform's order ID.

Shop order service

Implement ShopOrderService to handle the two responsibilities the webhook flow requires:

• updateStatus(Webhook $webhook, ...) — map $webhook->getSqState() (approved, cancelled, needs_review) to your platform's order status and persist it
• getCreateOrderRequest(string $orderReference): CreateOrderRequest — reconstruct the original order request for a given order (used during webhook acknowledgement)

The service also provides getReportOrderIds() and getStatisticsOrderIds() for optional delivery and statistics reporting.

Step 5 — Implement repositories

Repositories are the persistence layer. Implement each interface using your platform's database or storage system.

If your integration does not use the features behind the last three interfaces, no-op implementations (anonymous classes returning empty values) are sufficient.

Step 6 — Wire everything in the bootstrap

The bootstrap class registers all service implementations with ServiceRegister and then calls BootstrapComponent::init(). Order matters:

1. Register platform services (Configuration, ShopLoggerAdapter, EncryptorInterface, MerchantDataProviderInterface, OrderCreationInterface, StoreIntegrationServiceInterface, ShopOrderService, ShopOrderStatusesServiceInterface) before calling BootstrapComponent::init()
2. Call BootstrapComponent::init() — registers all core services, controllers, proxies, and events
3. Register repository overrides and webhook service overrides after BootstrapComponent::init()

Call Bootstrap::init() early in your application lifecycle, before any request that involves seQura is handled.

Step 7 — Build the checkout flow

The checkout flow has two API interactions.

Solicitation endpoint

Create an endpoint the frontend calls when the customer reaches the payment step. It asks seQura which payment methods are available:

$builder = new MyOrderRequestBuilder($orderData);
$response = CheckoutAPI::get()
    ->solicitation($storeId)
    ->solicitFor($builder);

// Returns available payment methods for the given cart and country
$paymentMethods = $response->toArray()['availablePaymentMethods'];

Your CreateOrderRequestBuilder implementation transforms your cart/order data into a CreateOrderRequest. The request must include cart items, delivery address, customer info, delivery method, and totals.

Identification form endpoint

After the customer selects a seQura payment method, fetch the HTML identification form:

$formResponse = CheckoutAPI::get()
    ->solicitation($storeId)
    ->getIdentificationForm($cartId, $product, $campaign);

// Render $formResponse->getIdentificationForm()->getForm() in an iframe

The $product parameter is the payment method code, and $campaign is optional.

Step 8 — Handle webhooks (IPN)

seQura sends Instant Payment Notifications when order statuses change. You must expose a publicly accessible POST endpoint—exempt from CSRF protection—that receives these notifications.

Payload transformation

seQura uses an m_ prefix on parameter keys and sends event instead of sq_state. Strip the prefix and rename the key before passing the payload to the library.

Processing the webhook

$response = WebhookAPI::webhookHandler($storeId)
    ->handleRequest($modifiedPayload);

// Return 200 on success, 400/410 on error

The storeId must be present in the payload so the handler can set the correct store context.

Webhook validator and handler

Extend WebhookValidator and WebhookHandler to resolve seQura orders from your repository. Both classes follow the same pattern—override getSeQuraOrderByOrderReference(string $orderRef): ?SeQuraOrder to look up the order in your storage. The base classes handle signature verification, state validation, and acknowledgement to seQura.

Register both overrides in your bootstrap after BootstrapComponent::init().

Integration checklist

Infrastructure

• Configuration service extending Configuration
• Logger service implementing ShopLoggerAdapter
• Encryptor service implementing EncryptorInterface

Platform services

• StoreIntegrationServiceInterface implemented
• ShopOrderStatusesServiceInterface implemented

Order management

• MerchantDataProviderInterface implemented
• OrderCreationInterface implemented
• ShopOrderService implemented

Repositories

• ConnectionDataRepositoryInterface
• CredentialsRepositoryInterface
• CountryConfigurationRepositoryInterface
• DeploymentsRepositoryInterface
• SeQuraOrderRepositoryInterface
• PaymentMethodRepositoryInterface (no-op if unused)
• OrderStatusSettingsRepositoryInterface (no-op if unused)
• StoreIntegrationRepositoryInterface (no-op if unused)

Bootstrap

• Platform services registered before BootstrapComponent::init()
• BootstrapComponent::init() called
• Repository overrides registered after BootstrapComponent::init()
• WebhookValidator and WebhookHandler overrides registered

Checkout flow

• CreateOrderRequestBuilder implemented
• Solicitation endpoint calling CheckoutAPI::get()->solicitation()->solicitFor()
• Identification form endpoint calling CheckoutAPI::get()->solicitation()->getIdentificationForm()

Webhook flow

• Public POST endpoint, exempt from CSRF
• Payload transformation (event → sq_state, m_ prefix removed)
• Calls WebhookAPI::webhookHandler($storeId)->handleRequest($payload)
• Returns 200 on success, 400/410 on error