PostFinance Checkout Shopware 6 Documentation

Documentation

1Prerequisites

If you don’t already have one, create a PostFinance Checkout account.

2Installation

  1. Install the plugin directly from the Shopware plugin store.

    Note
    You also have the possibility to install the plugin using composer. See FAQ.
  2. Log in to the backend of your Shopware store.

  3. Navigate to Settings → System → Plugins. Click on the menu caret and select the Install link of the plugin to install it.

    plugin installation
  4. Activate the PostFinance Checkout Payment plugin from the Plugin Manager.

3Configuration

  1. Navigate to Settings → Plugins → PostFinanceCheckout in your Shopware backend. Enter the PostFinance Checkout Space ID, User ID and Authentication Key that you can create an application user.

    plugin configuration

    If your store is configured for multiple sales channels, you may use different spaces for each store to configure different behaviours.

  2. Optionally after saving your configuration you can click on Set PostFinanceCheckout as default payment handler. This will set PostFinanceCheckoutPayment as the default payment handler for the selected sales channel.

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 Settings → Store → Payment.

4Payment method configuration

4.1Setup

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 Settings → Store → Payment.

payment method configuration

4.2Payment method rules

If you would like to restrict a payment method to certain conditions (B2B, cart amount, etc), you can create or choose a rule with the Availability Rule option in the shop backend.

payment method configuration availability rule

How to create a new Rule?

  1. Click on “Create new rule…” in the Availability rule option and fill out the modal form with conditions, as shown below.

payment method configuration create availability rule
  1. In this example the rule is as shown below:

    • Name: Payment method for B2B.

    • Priority: 1 (if you wish to prioritise when using several shipping methods, please adjust the value accordingly).

    • Conditions: Commercial customer | Yes Billing address: Country | Is one of | Switzerland

You can now select the rule in the desired payment method in the item availability rule.

It is also conceivable to add a further condition to the rule above, e.g. to make the payment method additionally possible only from a certain purchase value (e.g. 250.00).

In this case, add another condition using the AND link and insert the following in the second condition.

  1. Select the newly created rule and save the changes to the chosen payment method.

Applying this rule to a payment method will result in only those customers who meet the configured conditions.

4.3Customization

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.

5State graph

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.

5.1State mapping of Shopware orders

When the order gets abandoned also Order status goes to "cancel" after approx. 40 minutes. We also change the Payment status, and the Delivery status.

5.1.1General remarks regarding order statuses

We recommend that you only change the Order status once the Payment status has reached a final state.

5.2State mapping of Shopware payment status

Below you find a diagram that shows the state machine of Shopware for payment status including additional information for the state transitions.

shopware 6 stage graph order
  1. If the transaction is Authorized in PostFinance Checkout, the Shopware order payment status is marked as In Progress.

  2. If the transaction fails before or during the authorization process, the Shopware order payment status is marked as Failed.

  3. If the transaction fails after the authorization, the Shopware order payment status is marked as Cancelled.

  4. If the transaction invoice in PostFinance Checkout is marked as Paid or Not Applicable, the Shopware order payment status is marked as Paid.

5.2.1General remarks regarding payment statuses

We recommend that you do not change the payment status manually. If you do so, it may be changed again by the plugin.

5.3State mapping of Shopware delivery status

Below you find a diagram that shows the state machine of Shopware delivery status including additional information for the state transitions.

shopware 6 stage graph delivery
  1. If the transaction is Confirmed status in PostFinance Checkout, the Shopware order delivery status is marked as Hold.

  2. If the transaction in PostFinance Checkout is marked as Fulfill, the Shopware order delivery status is marked as Open.

  3. If the transaction is in Decline, Failed or Voided, the Shopware order delivery status is marked as Cancelled.

6Transaction management

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).

6.1Complete (capture) an order

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 Complete button.

Note
When the completion is pending in PostFinance Checkout the order will stay in pending state.
capture transaction

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 In Progress 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 Paid state in Shopware. You can now start the fulfillment process.

6.2Void a transaction

In order to void a transaction, open the order and click on the Cancel authorization button.

Note
You can only void transactions that are not yet completed.
void transaction

6.3Refund of a transaction

You have the possibility to refund already completed transactions. In order to do so, open the captured order. By clicking on the 3 dots (…​) on a line-item, you can refund the line-item partially (if it has a higher quantity than 1), or you can refund the whole line-item. In case the payment method does not support refunds, you will not see the possibility to issue online refunds.

refund transaction

You can carry out as many individual refunds as you wish until you have reached the total amount of the original order. The status of the order then automatically switches to complete.

Note
It can take some time until you see the refund in Shopware. Refunds will only be visible once they have been processed successfully.

6.4On hold orders

The delivery should not be done whilst the delivery state is Hold. 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.

You can find more information about manual tasks in our Manual Task Documentation.

6.5Limitations of the synchronization between PostFinance Checkout and Shopware

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.

6.6Tokenization

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 allow or force storage.

Note
Tokenization is not available for guest checkouts.

7Error logging

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.

8FAQ

8.1How to install the plugin using composer?

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-6

Once this done, continue with step 2 of the installation process. See Installation.

8.2How can I make the payment methods appear in the checkout?

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.

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.

9Sending emails with Flow Builder

In order for your emails to send when setting up custom flows using Flow Builder you must ensure that "Send order confirmation email" is disabled (located in the plugin settings).

If you you have already made seperate channel adjustments (using the channel dropdown in the plugin settings) you will have to ensure that the emails are disabled per channel accordingly.

10Troubleshooting

10.1Webhook error (API version not available)

Webhooks communication fails because of a reply saying HTTP 404 with this or a similar error in the response: {"errors":[{"code":"0","status":"404","title":"Not Found","detail":"Requested api version v1 not available, available versions are v2, v3."}]}

Solution: The Webhooks have to be updated. Shopware is using an API Version for all "URLs", which has to be updated in case shopware itself was updated.

11Support

If you need help, feel free to contact our support.