Refunds
Mollie has different options to handle refunds. You can use the Administration, the Mollie Dashboard, Flow Builder Events or the Shopware API.
This page explains all available options.
Please keep in mind, when starting a refund in Mollie, it takes about 2 hours before its confirmed. Until then, you can still cancel a pending refund. The order itself is still "paid" in that period.
Since version 2.2, the plugin contains a full Refund Manager. When we talk about the "Refund Manager", we talk about 2 things.
While the actual Refund Manager is a module within the Shopware Administration, it is also a core concept and service inside the plugin, that is also used by the Flow Builder and when refunding using the plugin API.
The basic idea is, to offer a simple API with meaningful data, that leads to a full refund workflow. It contains the financial refund through Mollie, an optional reset of the available product stock, and also the start of Flow Builder events. To offer everyone a good experience right from within Shopware, we've created the matching Administration module, which can be used, but is not the only way for the refund process.
If you have any ideas, we would love to hear these. We're always more than happy to improve our services for you.
The Refund Manager can be found in the Mollie Actions context button within the order in the Shopware Administration.
This will open a modal with the full Refund Manager.
The Refund Manager consists of 3 areas.
It shows you all line items and deliveries of your cart inside our "Editing Matrix" that can be used to prepare a refund. The center area contains all kinds of instructions along with the actual working area to start and finish a refund. In the bottom you see a list of all existing refunds. These refunds will be fetched directly from the Mollie Dashboard. This means that it does not only show refunds made inside Shopware, but also refunds that have been created in the Mollie Dashboard.
Let's start with a few refunds.
If you just want to refund the full order, then we have a separate button for this. This will collect all items and mark every item as refunded in Mollie.
Please keep in mind, it will not reset the stock. Resetting the stock needs explicit information provided by you (described later).
With this refund, and with all other refunds, you can also provide a custom bank/card statement description as well as an internal description, which will be used for the refund.
After your refund has been created, it will be displayed as PENDING in the list below.
If you only want to refund a custom amount, then simply enter any valid amount in the corresponding field. You can also add a description for your refund.
Once ready and verified, simply click on the refund button to start your custom refund.
If you need more than just a simple amount refund, then our Refund Manager allows you to also specify the quantity to be refunded. This helps you to identify what has already been refunded, and for what price it has been refunded.
This is the first time that we use our editing matrix.
The editing matrix shows you all line items and deliveries of the order. Just define the number of items you want to refund, as well as their price for the refund. You have the freedom to decide what you want to do. You can refund the original amount, or just a different amount for the item. Or you can decide to refund a quantity, or a mixture of both. All these preparations will then be aggregated to a final refund amount in our text field in the working area. This final refund amount, can also be adjusted again.
Using the editing matrix does also give you the option to reset the stock. Whenever you enter a quantity to be refunded, the reset-stock field is also filled in automatically (can be turned off in plugin configuration). This quantity is always the suggestion, so you can indeed adjust it to your needs. E.g. if your customer sends back 2 pieces of your product, but only 1 can be sold again, then just refund 2 pieces, and only use 1 piece for the stock reset.
Promotions in Shopware 6 are implemented as separate line items. This is also the way how they will be sent to Mollie.
If we have 2 products and 1 promotion, this means we have 3 separate line items in Shopware and Mollie.
When you want to refund all products that have been discounted, simply refund all products along with the full promotion line. This will lead to a final sum, that should match the expected amount to be refunded.
But what if you only want to refund a subset of the products that have been affected by a promotion? In this case, you always need to think about what should be done.
The complexity and endless possibilities of promotions and rules in Shopware does not allow us to "rebuild" why a product has been discounted. But also besides this, what would you refund if you have something like "Buy 2 get 1 for free", and the customer returns 1 item? Would you refund the full price? A discounted one? Nothing? That answer differs from merchant to merchant.
What the plugin can offer you is, that we read the composition of the promotion line item. This contains all products that have been discounted along with their quantity and price. That result has been added to the "Deduct Promotion" checkbox feature. Every product that has been discounted with a promotion, gives you the option to deduct the promotion value of that item directly within that line. When you use this, you do not have to refund the promotion line item itself, because the product price is already the reduced one.
This is a convenient way, but please always verify what you are doing!
Once your editing matrix is prepared, simply check your final refund amount, add an optional description and start the refund.
The existing refunds are visible in the bottom list of the Refund Manager. You can see the status of the refund (pending, refunded, ...), the description as well as the composition.
The composition gives you detailed information about what has been refunded with that entry.
Please keep in mind, not all types of refunds show you a composition. If you have created refunds without item information, like an amount-only refund, then no information about the items are available.
If you want to cancel a pending refund, just use the button for it inside the context menu of the item.
The refund process, if processed by Mollie, takes around 2 hours. Until then, the refund is still "pending". This means the only way to know that a refund is correctly done, is to hook into the webhooks that tell Shopware that the status is either "refunded" or "partially refunded".
Flow Builder allows you to use triggers for these Webhook payment status updates.
If you however want to immediately trigger something as soon as the refund has been started, then there's another Flow Builder trigger available which has the name "Mollie > Refund > Started".
This will be immediately fired when the Refund Manager refund has been called. This will also be called from the API or from the Flow Builder "Refund Action".
The Refund Manager has a built-in stock management which automatically increases the available stock for a product, if requested. The default implementation is working like the Shopware one, and increases the values based on SQL statements.
If you are a plugin or partner who is in charge of handling the stock for the shop, then Mollie offers you an easy
to use StockManagementInterface.
You can simply decorate the original Mollie stock manager, and replace it with your custom logic.
The interface is designed to give you everything you need to identify the item and create your own behaviour and conditions for a stock update.
Mollie will call the stock manager only as final step if the refund process worked without an error.
You might recognize a yellow background color appearing in your text fields within the editing matrix. This is the "Focus Color". When you start with your first input in a line, that field is highlighted, because your focus was on that. The color helps you when you have a longer list and want to see what items are refunded based on a quantity and what items might be refunded because you are refunding "money".
The focus color can be reset by either resetting the whole form, or a single line in the context menu of a line.
With all the combinations, it can just happen that rounding errors occur. This could however mean, that the refund amount is e.g. off by 1 cent. And you probably don't want to forget a single cent right? If the difference to the remaining amount is 5 cent, then a "fix" button will be visible. This one tells you that there is a slight difference, and allows you to easily adjust the amount.
You can also use our simple HTTP API endpoints to trigger either a full or a partial refunds. This is a perfect combination if you have automatic processes or other tools that you want to integrate.
Mollie uses the Shopware 6 API. This means that the credentials and tokens for the Shopware API are required to trigger these actions.
We differ between 2 types of APIs in our plugin.
The operational API endpoints are meant to work in an easy and logical way.
This means that you can simply provide parameters that 3rd party systems usually know, like the order number, amount and more.
The technical API endpoints however require the knowledge of internal Shopware IDs and information.
These are also used in our Shopware Administration modules.
FOR FULL SAMPLES, PLEASE SEE OUR SWAGGER PROJECT IN THE PLUGIN REPOSITORY!
Use this URL and provide the Shopware order number to start a full refund of your order. You can also add a custom description, so you know what this refund was all about.
# Full Refund
/api/mollie/refund/order?number=(swOrderNumber)
# Full Refund with custom description
/api/mollie/refund/order?number=(swOrderNumber)&description=(description)Use this URL and provide the Shopware order number as well as a custom amount for the partial refund. The custom description parameter is also available here.
# Partial Refund
/api/mollie/refund/order?number=(swOrderNumber)&amount=(amount)
# Partial Refund with custom description
/api/mollie/refund/order?number=(swOrderNumber)&amount=(amount)&description=(description)You can request the current aggregated refund data of a specific order. This is the request that is also used for the Refund Manager in the Administration.
POST /api/_action/mollie/refund-manager/dataUse this JSON request body.
{
"orderId" : "sw-order-id-123"
}This is a sample response with prepared data from the Refund Manager
{
"totals": {
"remaining": 25,
"voucherAmount": 0,
"pendingRefunds": 19.99,
"refunded": 0
},
"cart": [
{
"refunded": 1,
"shopware": {
"id": "xxx",
"label": "T-Shirt",
"unitPrice": 19.99,
"quantity": 1,
"totalPrice": 19.99,
"discountedPrice": 19.99,
"productNumber": "SWDEMO10007.1",
"promotion": {
"discount": 0,
"quantity": 0
},
"isPromotion": false,
"isDelivery": false
}
},
{
"refunded": 0,
"shopware": {
"id": "xxx",
"label": "Express",
"unitPrice": 0,
"quantity": 1,
"totalPrice": 0,
"discountedPrice": 0,
"productNumber": "SHIPPING",
"promotion": {
"discount": 0,
"quantity": 0
},
"isPromotion": false,
"isDelivery": true
}
}
],
"refunds": [
{
"id": "re_xxx",
"orderId": "ord_xxx",
"paymentId": "tr_xxx",
"amount": {
"value": "19.99",
"currency": "EUR"
},
"settlementAmount": {
"value": "-19.99",
"currency": "EUR"
},
"description": "Refunded through Shopware. Order number: 10031",
"createdAt": "2022-03-29T08:03:57+00:00",
"status": "pending",
"isFailed": false,
"isPending": true,
"isProcessing": false,
"isQueued": false,
"isTransferred": false,
"metadata": {
"type": "full",
"composition": [
{
"swLineId": "xxx",
"mollieLineId": "odl_1.xxx",
"swReference": "SWDEMO10007.1",
"quantity": 1,
"amount": 19.99
}
]
}
}
]
}If you want to use the refund manager as service, and start to refund quantities, or even reset the stock, then simply use this API endpoint for this.
POST /api/_action/mollie/refundPlease send these as JSON body in the POST request.
{
"orderId" : "sw-order-id-123",
"amount": 15,
"items" : [
{
"id" : "sw-order-item-id-123",
"quantity": 3,
"amount" : 5,
"resetStock": 2
}
]
}The JSON above is the full representation. Please keep in mind there are different options you have.
If you skip the amount and the items, then a full refund will be created for the order.
If you provide an amount, but no items, then a refund based only on a custom amount will be done without any items.
The Mollie plugin offers a separate action for the Shopware Flow Builder. This helps you to trigger full refunds based on trigger events and conditions within the Shopwar eco-system.
You can read more about the Flow Builder here: Flow Builder Integration
To create a new refund based on Flow Builder, just use the action "Refund Order (Mollie)". This configuration window will tell you everything you need to take care off, such as disabling any additional automations that might interfere with this action.
That's it :)
- Apple Pay
- Apple Pay Direct
- Bancontact
- Belfius
- Billie
- Credit Card
- EPS
- Giftcard
- Giropay
- iDEAL
- in3
- KBC / CBC
- Klarna Pay Later
- Klarna Pay Now
- Klarna Slice It
- PayPal
- Paysafecard
- POS Terminals
- Przelewy24
- SEPA Bank Transfer
- SOFORT
- TWINT
- Voucher