If you don’t already have one, create a PostFinance Checkout account.
Install the plugin directly from the Shopware plugin store.
|You also have the possibility to install the plugin using composer. See FAQ.|
Log in to the backend of your Shopware store.
Navigate to Configuration → Plugin Manager and to Management → Installed. Click on the
Install button of the plugin to install it.
Activate the PostFinance Checkout Payment plugin from the Plugin Manager.
Reload the page.
Navigate to Configuration → Plugin Manager and to Management → Installed in your Shopware backend, click on the
Edit button of the plugin and enter the PostFinance Checkout Space ID, User ID and Authentication Key that you can create in the setup assistant. Alternatively, you can manually create an application user.
If your store is configured for multishop, you may use different spaces for each store to configure different behaviours.
Optionally disable downloading invoice and packing slip. These settings allow customers to download the documents from their order overview in the Shopware frontend.
|Payment methods will only be available in your store once you assign them to shipping method(s). See Payment method configuration|
After saving the configuration and clicking on the
Synchronize button, the payment methods are created in the Shopware store and the necessary webhooks are set up.
The main configuration is finished now. You should see the payment methods in your checkout. To view the payment method configuration in the backend of Shopware go to Configuration → Payment Methods.
The PostFinance Checkout payment method configurations are synchronized automatically into the Shopware store. There are just a few payment method settings in the Shopware store in Configuration → Payment methods.
|Additional payment methods are directly added in PostFinance Checkout. This can be done in the setup assistant. Changes are synchronized automatically.|
If you want to change the payment method description, title, logo, etc you need to do this in the payment method configuration. Changes will be synchronized automatically.
The Payment Process of PostFinance Checkout is completely standardized for every payment method you can process. This gives you the ability to simply add a payment method or processor without changes inside of your Shopware configuration. An overview about the states and the payment processes of PostFinance Checkout can be found in the Payment Documentation.
In the following section we provide you an overview about how the PostFinance Checkout states are mapped into the Shopware State graph for orders and payment states.
Below you find a diagram that shows the state machine of Shopware for orders including additional information for the state transitions.
If the transaction is
authorized in PostFinance Checkout, the Shopware order is marked as
Clarification required. This can be changed
in the plugin configuration. It’s also possible to define different statuses for
If the transaction fails during the authorization process, the Shopware order is either marked as
Cancelled/rejected or removed from the database, depending on the configuration.
Whether an order should be removed from the database or marked as
Cancelled/rejected if the corresponding transaction fails can be configured in the plugin configuration. The latter is the default behaviour.
If the transaction in PostFinance Checkout is marked as
fulfill, the Shopware order is marked as
Ready for delivery, indicating that it can now be fulfilled. Once the shipment has been created, we recommend to change the order’s status.
If the transaction’s authorization is voided or the risk assessments indicate that the order should not be fulfilled, the order is marked as
We recommend that you only change the order status to indicate that shipping has taken place. If you change it before the transaction has reached a final state in PostFinance Checkout, the plugin may changed the order status again. If you want different order statuses to be set, you can change the behaviour in the plugin configuration.
Below you find a diagram that shows the state machine of Shopware for payment status including additional information for the state transitions.
If the transaction in PostFinance Checkout is
authorized, the payment status of the Shopware order is set to
If the transaction fails during the authorization process, the payment status of the Shopware order is set to
The process has been canceled.
If the transaction in PostFinance Checkout is
completed, the payment status of the Shopware order is set to
Completely invoiced. At this point, the transfer of the amount has been initiated and the transaction amount can no longer be changed. However, the order has not yet been fulfilled and the delivery should not be started.
If the transaction’s authorization is voided, the payment status of the Shopware order is set to
The process has been canceled.
Once the invoice is paid, the payment status of the Shopware order is set to
Completely paid. This also applies if the invoice is not traceable due to external administration.
If the invoice is derecognized and the payment can no longer be expected, the payment status of the Shopware order is set to
The process has been canceled.
We recommend that you do not change the payment status manually. If you do so, it may be changed again by the plugin.
You can capture, cancel and refund transactions directly from within the Shopware backend. Please note if you refund, void or capture transactions inside PostFinance Checkout the events will be synchronized into Shopware. However, there are some limitations (see below).
You have the possibility for your transactions to have the payment only authorized after the order is placed. Inside the connector configuration you have the option, if the payment method supports it, to define whether the payment should be completed immediately or deferred.
In order to capture a transaction, open the order and click on the
|When the completion is pending in PostFinance Checkout the order will stay in pending state.|
Deferred payment completion
Retailers often have the case that they want to authorize transactions only and start the fulfillment process once all items are shippable. This is also possible with PostFinance Checkout.
However, certain processes should be followed. If you have configured payment completion to be deferred you should capture the transaction before you initiate the shipment
as it can always happen that a completion fails. If you want to be sure that you do not ship items for which you have not been paid you should postpone the shipment until
the fulfill state is reached. Initially the transaction will be in the
Authorized state in PostFinance Checkout and
Clarification required in Shopware. If you want to start the fulfillment process make sure you initiate the completion process as described above. Once the completion was successful the order will switch into the
Fulfill state in PostFinance Checkout and into
Processing state in Shopware. You can now start the fulfillment process.
In order to void a transaction, open the order and click on the
|You can only void transactions that are not yet completed.|
You have the possibility to refund already completed transactions. In order to do so, open the captured order. By clicking on the
Refund button, the window for refunds will open. In case the payment method does not support refund, you will not see the possibility to issue online refunds.
You can make refunds based on product quantity. In order to do so, open the credit memo window and enter the amount of products you wish to refund to your customer.
You can carry out as many individual refunds as you wish until you have reached the quantity of the original order. The status of the order then automatically switches to complete.
|It can take some time until you see the refund in Shopware. Refunds will only be visible once they have been processed successfully.|
As long as the delivery should not be done the state of the order will be in
Clarification required. This happens when the transaction in PostFinance Checkout
has not reached the fulfill state.
There are essentially two reasons why this can happen:
The transaction is not completed. In this case you have to complete the transaction as written above.
We are not able to tell if you should fulfill the order. The delivery decision is done automatically. If this does not happen within the defined time frame, PostFinance Checkout will generate a manual task which you should observe and follow the instructions. When there is a manual task we will also display it in the Shopware Backend.
You can find more information about manual tasks in our Manual Task Documentation.
Please note that captures, voids and refunds done in PostFinance Checkout are synchronized. However, there are some limitations. Inside PostFinance Checkout you are able to change the unit price and the quantity at once. This can not be done in the Shopware backend. We therefore recommend that you perform the refunds always inside the Shopware backend and not inside PostFinance Checkout. If a refund cannot be synchronized it will be sent to the processor but it could be that you do not see it inside your Shopware backend.
You can find more information about Refunds in PostFinance Checkout in our Refund Documentation.
In case the payment method supports tokenization you can store the payment details of your customer for future purchases.
In order to use this feature make sure that the One-Click-Payment Mode in your payment method configuration is set to
|Tokenization is not available for guest checkouts.|
The extension uses the Shopware logging functions which are automatically active in your Shopware store. The extension will log various unexpected errors or information which can help identify the cause of the error. You can find the logs on the server of your store in the var/log/ folder.
You can install the plugin using composer by updating the
composer.json file in the root directory of your Shopware store and wait for Composer to finish updating the dependencies.
composer require postfinancecheckout/shopware-5
Once this done, continue with step 2 of the installation process. See Installation.
Make sure that you followed the Configuration section by stating your PostFinance Checkout space ID and application user’s access information in the Shopware backend. By saving the configuration form the synchronization of the payment methods and the set up of the webhooks are initiated.
Make sure that you have synchronized the plugin’s settings by pressing the "Synchronize" button.
Make sure that the payment methods are assigned to at least one shipping method.
If this does not solve the problem, it could be that you use a special fee or coupon module that we do not support. Try to disable this plugin and see if it helps. The payment methods are only displayed if the plugin’s total calculation matches the actual order total.
If you need help, feel free to contact our support.