Direct line to ALBIS
JSON-RPC integration with the ALBIS platform - credit check and application in real time, without email back-and-forth.
ALBIS Leasing.
Leasing contracts directly in the Shopware checkout - with live API, automatic status polling, Flow Builder integration and mail templates per sales channel.
Contents of this doc
What does the plugin do?
ALBIS Leasing as a full payment method.
A complete leasing flow inside Shopware: API integration, application path in checkout, mail integration, optional detail page display - from a single source, no external tools.
What does your shop get?
A complete connection to the ALBIS Leasing platform - right inside the Shopware checkout.
The plugin extends Shopware 6 with its own payment method "ALBIS Leasing". In checkout, the business customer fills in all leasing data themselves, the plugin sends it to the ALBIS API, the credit check runs in real time, and the customer gets an answer immediately. You as the merchant receive all data in parallel and can process the contract as usual. Afterwards the plugin polls the ALBIS status fully automatically in the background and can adjust the Shopware order status if needed.
For business customers
Specifically for B2B leasing - company data, bank details, optionally director data above a defined order value.
Multi-shop capable
Activation and configuration per sales channel - different channels can use different ALBIS accounts.
In v2.5 · second contract
From version 2.5 (SW 6.7) the plugin config supports an additional set of ALBIS credentials and a second product group - for shops with two ALBIS merchant contracts.
Per sales channel
Application confirmation to customer, application data to merchant, status updates - overridable per sales channel. Details →
Inline leasing rate
Optional: show the ALBIS payment method on the product detail page when minimum requirements are met. Details →
Installation
Six steps - about 20 minutes.
Standard Shopware plugin installation, with two migrations for the ALBIS product groups and configuration defaults.
Download ZIP
Pick the ZIP variant for your Shopware version from the downloads section below. Three versions available:
- v2.5.86 for SW 6.7 (current)
- v2.2.96 for SW 6.6
- v2.1.73 for SW 6.5
Plugin manager → Upload
In Shopware admin: Settings → System → Plugins → "Upload plugin". Pick ZIP, upload, then click "Install".
Activate
Activate the plugin in the plugin overview. The required migrations (two of them) run automatically - they create the albis_product_group table and configuration defaults.
Assign sales channel
In the plugin config: activate per sales channel or globally. Without this assignment the payment method does not appear.
Enter ALBIS credentials
API endpoint, username and password - provided by your ALBIS contact. SSL is required.
Test & go
In the plugin backend there is a "Test API connection" button. Click it - when the connection works, you are ready for the first test order.
Configuration
All backend fields - documented.
The plugin configuration in the Shopware admin per sales channel or globally - every field explained here.
Important before going live
Verify credentials and product groups.
After entering the configuration, verify both points: First, the ALBIS API connection via the API test button (per contract) - if the test fails, no application can be submitted. Second, the selected product group - it must belong to the matching credentials, otherwise ALBIS will reject the leasing application outright. For setups with two credentials (v2.5), this applies to both contracts separately.
URL from your ALBIS account
Full URL of your ALBIS API endpoint - live or test, depending on what ALBIS provides. Required field.
API credentials for contract 1
Entered in the plugin backend. Password protected as a type=password field. Only ALBIS can issue these credentials.
Optional - credentials for contract 2
Additional credentials for a second ALBIS merchant contract, in case ALBIS runs two separate contracts internally. Only from v2.5 (SW 6.7).
Check the connection immediately
Placed directly below the credentials - click checks the ALBIS API connection live from the backend. Contract 1 and contract 2 each have their own button.
Dropdown in the backend
Pick an ALBIS product group from the dropdown that matches the entry in your ALBIS account. Only groups available for the credentials of contract 1 are shown. Submitted with the application, not visible to customers.
Second product group (v2.5)
Additional product group - relevant when ALBIS prescribes a different group per contract. Selection is restricted to groups valid for contract-2 credentials.
Value between 0 and 5 %
Optional - included in the leasing rate calculation and submitted to ALBIS. Default value: 5.
Order value limit from 500
The cart value (net) from which additional managing-director contact data is requested. Default value: 500.
Suggest ALBIS payment method
Boolean - if enabled, the ALBIS payment method is already suggested on the product detail page, provided all minimum requirements are met. Default: on.
Double safety
Optional BCC address for all ALBIS order confirmations - for seamless internal oversight. Leave empty if no extra copy is needed.
Couple order status to ALBIS
Boolean - if enabled, the Shopware order status is automatically aligned to the ALBIS status: on cancellation/rejection it is set to "cancelled", on billing the order is completed and the payment marked as "paid". Default: off.
Main features
What the plugin actually does.
API integration, Flow Builder hook-up, in-backend API test, mail templates and optional detail-page display - the features actually shipped in the three plugin versions.
Additional credentials
From v2.5.86 (SW 6.7): an additional set of ALBIS credentials (Username 2 / Password 2) and a second product group in the plugin config. Useful when ALBIS runs two separate merchant contracts for your shop internally.
Business event after application
New Shopware business event albis.leasing.application.placed - available in Flow Builder after every submitted application. Bundled CreateTagAction automatically tags the order (e. g. albis-pending).
Automatic status updates
New CLI command bin/console albis:check-status polls the ALBIS status of open applications in phases: every 5 minutes in the first half hour, then hourly up to 4.5h, then daily up to 90 days. Fully automatic via scheduled tasks.
ALBIS status on the order
Plugin automatically creates the custom field set "ALBIS Leasing" on the order entity - ALBIS status, application number and last check are directly visible on the order in the backend. Status history in dedicated table albis_status_tracking.
Align Shopware order status
Optional config coupleOrderStatus: on ALBIS cancellation or rejection, order, payment and delivery status are set to "cancelled" automatically. On billing, the order is completed and the payment marked as "paid".
Real-time response
After the application is submitted in checkout, the ALBIS credit check runs in seconds - answer comes back before the customer leaves the page.
Inside the backend
Dedicated "Test API connection" button (endpoint /api/_action/albis-api/verify) - verifies the stored credentials directly against the ALBIS endpoint, with clear error display on bad data.
Application & status
Mail templates for application confirmation and status updates to customer and merchant - registered in the Shopware mail manager, customisable per sales channel. Optional BCC for internal overview. Details →
Per sales channel
Optionally activatable via plugin config (detailPageDisplay): show the ALBIS payment method on the product detail page when all minimum requirements are met. Details →
Own DAL entity
AlbisProductGroup as a standalone Shopware entity with EntityCollection and EntityDefinition - selectable in the backend via sw-entity-single-select.
Encrypted transport
The ALBIS API only accepts HTTPS connections with TLS 1.2 or newer. Required before activation.
DE + EN out of the box
All storefront and admin strings translated to DE and EN via Shopware snippets - further languages can be added via the standard snippet mechanism.
Downloads
Three plugin ZIPs.
One ZIP per Shopware major version. Click the download button for the version you need.
AlbisLease v2.5.86
For the current Shopware 6.7 line. Full feature set including Contract 2 and Shopware Flow Builder integration.
Size: 164 KB
MD5: bdfc93b2fddc5c1acf8447df18f13079
AlbisLease v2.2.96
Stable version for Shopware 6.6 - identical feature set to v2.1.73, compatible with SW 6.6.
Size: 148 KB
MD5: 1344a657a7f90a8737430b75c2a18301
AlbisLease v2.1.73
Stable main release for Shopware 6.5 - still maintained. With API test component and AlbisProductGroup entity.
Size: 140 KB
MD5: 4b95eab6b8ff5c32b55b320fe35e4592
MD5 verification
Every download with an MD5 checksum - verify before installation.
On your system: md5sum AlbisLease-v2.5.86-SW6.7.zip - the result must match the MD5 value shown here. If not, the file is corrupted or tampered with - do not install.
Frequently asked questions · FAQ
FAQ on the ALBIS plugin.
The questions we get most often about ALBIS leasing in Shopware - from real customer enquiries.
Do I need my own ALBIS contract?
Yes. The plugin is an interface to the ALBIS Leasing platform - the actual merchant contract you need to sign directly with ALBIS Leasing AG. Your ALBIS contact then provides the API credentials, which you enter into the plugin.
Why can't I select the product groups directly?
On initial installation, the product group dropdowns are empty at first - this is intentional. The plugin can only load the available groups from the ALBIS API once valid credentials are present.
Correct order:
- First, enter only the credentials (username, password, API endpoint) and save
- In the second step - after the config reload - the product groups appear in the dropdown for selection
- Pick the matching product group and save again
For a second contract (v2.5) the same applies: first save username 2 / password 2, then product group contract 2 becomes selectable.
Do I need to configure a second contract?
No. The second contract is entirely optional. The fields username 2 · password 2 and product group contract 2 simply stay empty if you only have one ALBIS merchant contract.
The plugin then uses only the first contract - the contract-2 fields are only there in case ALBIS issues you two separate contracts internally (e.g. for different business areas or product types).
Which Shopware version do I need?
There are three plugin versions, one per active Shopware major line:
- v2.5.86 for Shopware 6.7
- v2.2.96 for Shopware 6.6
- v2.1.73 for Shopware 6.5
Cross-installation (e. g. the SW 6.7 version on a SW 6.6 shop) does not work - the Composer constraints prevent it.
What does the plugin cost?
The plugin itself is part of an ALBIS merchant contract and is free of charge within that relationship. You do not pay a plugin license to Stone & Water - the conditions follow from your ALBIS contract. If you need an individual setup or customisations, get in touch.
How does the credit check work?
The customer enters their company and (optionally) director data in checkout. The plugin sends them via JSON-RPC to the ALBIS API. ALBIS performs the credit check in real time and responds within seconds - with acceptance, rejection or "in review". The status lands on the order and in the status mail to customer and merchant.
How does the automatic status polling work?
After a leasing application is submitted, the plugin stores it in a dedicated table albis_status_tracking. The CLI command bin/console albis:check-status runs in phases:
- Fast phase: 0-30 min after submission → check every 5 minutes
- Hourly phase: 30 min - 4.5h → check hourly
- Daily phase: 4.5h - 90 days → check once a day
- Expired: After 90 days a final API check is done: on status "billed" the order is completed, otherwise polling ends without further status change - the merchant decides manually
Polling runs fully automatically via Shopware scheduled tasks. As soon as an ALBIS end state is reached (acceptance, rejection, cancellation, billing), polling stops for that application. With the config option coupleOrderStatus, the Shopware order status is additionally adjusted automatically.
Can I use the plugin with Flow Builder?
Yes, from v2.5.86 (SW 6.7). The plugin registers the business event albis.leasing.application.placed, which is available in Flow Builder after every submitted application. You can use it e. g. to automatically tag the order with albis-pending or trigger an additional mail.
Can B2C customers use leasing?
No. ALBIS leasing is for business customers (B2B). Private individuals are explicitly excluded - this follows from the ALBIS contract model, not from the plugin. If you want to offer B2C financing, you need a different provider.
What happens on rejection?
ALBIS returns the rejection to the plugin, the status on the order is set to "rejected", and both customer and merchant receive a status mail. The order itself remains - you can decide whether to offer the customer an alternative payment method or cancel the order.
Can I customise the mail templates?
Yes, fully. All four mail templates are registered in the Shopware mail manager and can be edited like any other Shopware mail - with Twig, sales channel override and all standard variables plus the ALBIS-specific ones like {{ albis.application.contract }}. More details →
How do I verify the download?
Every download above has an MD5 checksum. On your system after the download: md5sum AlbisLease-v2.5.86-SW6.7.zip. The result must match the displayed MD5 value - otherwise the file is corrupted or tampered with.
Who installs the plugin?
You or we. The installation is a standard Shopware plugin procedure and takes someone familiar with Shopware 20-30 minutes. If you prefer to outsource it: albis@stoneandwater.online - we set up the entire thing, including a test order with a real ALBIS response.
What about Shopware 5?
An older Shopware 5 version (AlbisPayment 5) still exists, but is no longer actively developed - Shopware itself has discontinued official support for SW 5. If you are on SW 5, we recommend migrating to SW 6.7 and the current plugin version v2.5.86.
Troubleshooting · Known Issues
Typical setup pitfalls.
The points most often overlooked during setup - with a clear fix.
Assign ALBIS payment to the sales channel
Most common error after installation: plugin is active, credentials are entered - but ALBIS does not appear in checkout. Reason: the payment method must be explicitly assigned per sales channel.
How to fix:
- In the admin:
Settings → Sales Channels → [Your channel] - Open the "Payment & Shipping" tab
- Under "Payment methods" add "ALBIS Leasing"
- Save, clear cache
Optionally set it as the default payment method, not required though.
Set up a cronjob for scheduled tasks
The polling system uses Shopware scheduled tasks. For these to run, a cronjob on the server must execute the scheduled-task worker. Without a cronjob, polling stops - even if everything else is configured correctly.
Cronjob (every 5 minutes recommended):
*/5 * * * * cd /var/www/shop && bin/console scheduled-task:run --time-limit=290
Alternative - trigger manually: The order overview in the backend has a button that triggers status polling for an individual order manually - useful for tests or when the cronjob is not running.
Check if the cronjob runs: bin/console scheduled-task:list - the "nextExecutionTime" column shows the next scheduled run. If this is in the past and not updating, the cronjob is not running.
Several possible causes
If the "Test API connection" button in the backend reports an error, check these in order:
- SSL required: ALBIS only accepts HTTPS endpoints - don't enter HTTP URLs
- Credentials: username and password exactly as provided by your ALBIS contact - no extra whitespace at start or end
- Endpoint URL: live and test endpoints are different - check which one ALBIS has enabled for you
- Firewall/Proxy: the server must allow outbound HTTPS to the ALBIS API - with restrictive hosts, the ALBIS domain may need to be allow-listed
Mail templates active per sales channel?
If status mails are not arriving, the cause is usually not the plugin itself but Shopware mail settings:
- Mail sender: are the default sender addresses set on the sales channel?
- Mail templates per sales channel: templates are registered globally but assigned per sales channel - verify in multi-channel setups
- Message queue: mails are sent through the Shopware message queue - the
messenger:consumeworker must be running (see cronjob above) - SMTP config: if using an external SMTP server, verify the credentials in the Shopware mail configuration
Technical details
On Shopware standards.
Symfony services, DAL-compliant data access, Vue 3 in admin. No core patches, no hacks.
Compatibility
ALBIS integration
Prerequisite: ALBIS merchant contract. API credentials are provided by your ALBIS contact.
GDPR
All contract and customer data is stored in the Shopware database. Credit checks happen at ALBIS - ALBIS is the responsible party under GDPR. Data processing agreement with ALBIS required.
Support
For questions on installation, configuration or for bugs: albis@stoneandwater.online
Ready to set it up?
We install it.
From plugin upload via ALBIS API configuration to test order - we handle the entire setup if you want.