PostFinance Checkout OXID 4.8

Documentation

1Prerequisites

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

2Installation

  1. Download the extension.

  2. Extract the files and upload them to the root directory of your store using FTP/SSH.

  3. Login to the backend of your OXID eSales store.

  4. Navigate to Extensions → Modules and activate the PostFinance Checkout module.

You may wish to install the following extensions to enhance your and your customer’s experience:

FrontendOrderList This extension allows to restrict customer order overview based on transaction status. OrderListStatus This extension allows to restrict & sort admin order overview based on transaction status. The OXID eSales system only references orders with status New, Finished and Problems, while PostFinance Checkout references more states, see State graph.

3Configuration

  1. Under Extensions > Modules > PostFinance Checkout, switch to the settings of the activated module and enter the PostFinance Checkout Space ID, User ID and Authentification Key that you can create an application user.

    Payment configuration

    If you are using EE with multistore, the settings under Global Settings are shared over all stores. You may use different spaces for each store to configure different behaviours.

  2. After saving the configuration, the payment methods are created in the OXID eSales store and the necessary webhooks are set up.

    Note
    		 Payment methods will only be available in your store once you assign them to shipping method(s). see Payment method configuration

  3. Optionally disable downloading invoice and packing slip. These settings allow customers to download the documents from their order overview in the OXID eSales frontend.

  4. Optionally change the debug level which increases what information is logged in your /logs folder, see Error logging.

The main configuration is now finished. You should see the payment methods in your checkout. To view the payment method configuration in the backend of OXID eSales eSales go to Shop Settings > Payment Methods.

4Payment method configuration

4.1Setup

The PostFinance Checkout payment method configurations are synchronized automatically into the OXID eSales store. There are just a few payment method settings in the OXID eSales store under Shop Settings → Payment Methods.

To be available in your store, payment methods must be assigned to shipping method(s). This can be done as follows:

  1. Navigate to Shop Settings → Shipping Methods and select the shipping method where the payment method(s) should be available.

  2. Switch to the Payment tab, and select Assign Payment Methods.

  3. Drag the PostFinance Checkout payment methods which should be available into the right column.

4.2Customization

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 Magento 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 OXID eSales State graph for orders.

5.1State mapping of OXID eSales orders

OXID eSales only shows by default the order states New, Finished and Problems.

  • The order status New contains all orders that are in state Fulfill.

  • The order status Problems contains all orders that need your manual attention or are not considered to be ready for fulfillment (e.g Authorized and Completed)

  • The order status Finished contains all failed orders.

In order to map the states from PostFinance Checkout to the OXID eSales status, you should install the OrderListStatus plugin. You will then get more information about the order state in PostFinance Checkout.

Below you find a diagram that shows the state machine of OXID eSales for orders including additional information for the state transitions.

state graph

5.2State mapping of OXID eSales payment states

OXID eSales does not have a separate invoice entity. However, we track the payment state of an order. An order is marked as paid if the following conditions are fulfilled:

  • A transaction is in the state Fulfill.

  • The invoice in PostFinance Checkout has the state N/A or paid

6Transaction management

You can capture, cancel and refund transactions directly from within the OXID eSales backend. Please note if you refund, void or capture transaction inside PostFinance Checkout the events may not be synchronized into OXID eSales.

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, navigate to Administer Orders → PostFinance Checkout Transactions, open the transaction and click on the Complete button.

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

6.2Void a transaction

In order to void a transaction, open the transaction and click on the Void 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 transaction and click on the Refund button. In case the payment method does not support refund, you will not see the possibility to issue online refunds.

refund transaction

You can make refunds based on product quantity. In order to do so enter the amount of products you wish to refund to your customer.

refund transaction2

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.

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

6.4On hold orders

As long as the delivery should not be done the state of the order will be in PostFinance Checkout_Completed. 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.

  • As long as we are not able to tell you 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 OXID eSales Backend.

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

6.5Limitations of the synchronization between PostFinance Checkout and OXID eSales

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 OXID eSales backend. We therefore recommend that you perform the refunds always inside the OXID eSales 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 OXID eSales 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 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 /logs folder. You have the option to change the debug level which increases what information is logged in your /logs folder:

  • Error (Default): Logs unexpected errors only.

  • Debug: Logs more information helpful for debugging.

8FAQ

8.1How 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 OXID eSales 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.

9Support

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