WeArePlanet Magento 2

Documentation

1Prerequisites

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

2Installation

  1. Update the composer.json file in the root directory of your Magento store and wait for Composer to finish updating the dependencies.

    composer require weareplanet/magento-2

  2. Enable the extension and clear the static view files.

    bin/magento module:enable WeArePlanet_Payment --clear-static-content

  3. Register the extension and initiate the database migrations.

    bin/magento setup:upgrade

  4. Recompile the Magento project.

    bin/magento setup:di:compile

  5. Clear the Magento store’s cache.

    bin/magento cache:flush

If you do the installation via FTP upload with our GitHub repositories, ensure that you are using: - the magento-2 repository, if your magento version is higher than or equal than 2.4

3Configuration

3.1Main Configuration

  1. Navigate to Stores → Configuration → Sales → WeArePlanet Payment in your Magento backend and in the section General enter the WeArePlanet User ID and Authentification Key that you can create an application user.

    application user configuration

  2. You need to switch the configuration scope to Main Website to enter the space id.

    space configuration

  3. After saving the configuration, the payment methods are created in the Magento store and the necessary webhooks are set up.

The setup is now finished. You should see the payment methods in your checkout. To view the payment method configuration in the backend of Magento go to Stores → Configuration → Payment Methods. Make sure you are in the Website configuration scope to view the payment methods.

Most of the payment method configuration is done in WeArePlanet. After following the steps of the previous steps, the WeArePlanet payment method configurations will be synchronized automatically into the Magento store. There are just a few payment method settings in the Magento store in Stores → Configuration → Sales → Payment Methods.

payment method configuration

3.1.1Line Items

By default the plugin calculates the line items as accurate as possible. The creation of the transaction is in that case possible only when correct data is transmitted.

The plugin allows you to control the line items calculation under Stores → Configuration → WeArePlanet Payment in the section Line Items:

line items magento2

There you have the possibility to set Enforce Consistency to No-

In this case the transaction is created even if the line items calculation is not 100% correct. This can happen if you are using for example third-party plugins (e.g. VAT calculation plugins, voucher plugins).

Note
 This setting implies that the plugin is collecting wrong data (e.g. VAT) which might lead to wrong data in the system.

4Payment Method Configuration

4.1Setup

The WeArePlanet payment method configurations are synchronized automatically into the Magento store. There are just a few payment method settings in the Magento store in Stores → Configuration → Sales → Payment Methods. To see the WeArePlanet payment methods, you need to switch the configuration scope to Website

payment method configuration

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.

4.3State mapping of Magento orders

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

magento2 state graph order

  1. If the transaction is authorized in WeArePlanet, the Magento order is marked as Hold Delivery. As long as the transaction is in WeArePlanet in state pending, the order will appear in Magento as Pending Payment. In case the transaction timed out the transaction will switch into cancel state.

  2. If the transaction fails during the authorization process, the Magento order is marked as Canceled.

  3. In case the delivery indication is pending, the order within Magento will move into Payment Review (in this case you have to decide the outcome of the delivery indication e.g. You have configured to manually check transactions without 3d Secure). In such situations a manual task is created and an alert appears in the WeArePlanet & Magento backends. You can then resolve the manual task within the WeArePlanet backend. This changes the transaction status, which is transmitted back to Magento. See more details in [On hold orders].

  4. If the transaction’s authorization is voided or the risk assessments indicate that the order should not be fulfilled, the order is marked as Processing.

  5. If the transaction in WeArePlanet is marked as fulfill, the Magento order is marked as Processing, indicating that it can now be fulfilled. Once the shipment has been created, we recommend to change the order’s status.

4.3.1Order Status Label Update

To update the Order status label please navigate to Stores > Order Status > NameOfTheStatus, and update the label.

4.4State mapping of Magento invoices

Below you find a diagram that shows the state machine of Magento for Invoices including additional information for the state transitions.

magento2 state graph invoice

  1. If the transaction in WeArePlanet is authorized, the invoice status of the Magento order is set to Pending.

  2. If the transaction fails during the authorization process, the invoice status of the Magento order is set to Canceled.

  3. If the transaction’s authorization is voided, the invoice status of the Magento order is set to Canceled.

  4. Once the invoice is paid, the invoice status of the Magento order is set to Paid. This also applies if the invoice is not traceable due to external administration (invoice not applicable).

5Transaction Management

You can capture, cancel and refund transactions directly from within the Magento backend. Please note if you refund, void or capture transaction inside WeArePlanet the events will be synchronized into Magento. However, there are some limitations (see below).

5.1Complete (capture) an order

You have the possibility for your transactions to have the invoice created and 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 invoice and click on capture.

Note
 When the completion is pending in WeArePlanet the invoice will stay in pending state.
magento2 capture

5.2Void a Transaction

In order to void a transaction, open the invoice and click on the cancel button. This will cancel the invoice and void the transaction.

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

5.3Refund of a Transaction

You have the possibility to refund already completed transactions. In order to do so, open the invoice of the captured order and click on Credit Memo. In case the payment method does not support refund, you will not see the possibility to issue online refunds.

magento2 refund1

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.

magento2 refund2

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 Magento. Refunds will only be visible once they have been processed successfully.

5.4On Hold Orders

As long as the delivery should not be done the state of the order will be in On Hold. This happens when the transaction in WeArePlanet 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, WeArePlanet 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 Magento Backend.

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

5.5Limitations of the Synchronization between WeArePlanet and Magento

Please note that captures, voids and refunds done in WeArePlanet are synchronized. However, there are some limitations. Inside WeArePlanet you are able to change the unit price and the quantity at once. This can not be done in the Magento backend. We therefore recommend that you perform the refunds always inside the Magento backend and not inside WeArePlanet. 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 Magento backend.

You can find more information about Refunds in WeArePlanet in our Refund Documentation.

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

6Backend Orders

You can create orders inside Magento also from the Magento Backend. If you create the transaction from the backend and select a payment method created by WeArePlanet then we are using the Charge Flow Feature of WeArePlanet. This means that we first check if the payment method allows to charge the customer without customer interaction (i. e. invoice). If not and you did not select from the dropdown to use a token with stored payment information we are going to trigger the charge flow process you configured to ask the buyer for the payment details.

moto token

You can find more information about charge flows in our charge flow documentation.

7FAQ

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

Make sure that you followed the Configuration section by stating your WeArePlanet space ID and application user’s access information in the Magento 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.

7.2Is OneStepCheckout supported?

Our WeArePlanet Magento 2 Plugin supports the major one-step checkouts out of the box. In case you use one of the listed checkouts below we can guarantee operability with the latest build of the plugin.

The following OneStepCheckout for Magento 2 are supported:

Checkout Suite (One Page/Step) M2 One Step Checkout for Magento 2

8Troubleshooting

8.1"Unique Constraint Violation Found" during installation

This issue can happen in case the installation failed or you used the plugin already in another context. We recommend that you delete all payment method configurations in the database of the webshop and then simply enter your credentials again as described in this manual.

This should finally trigger the creation of the payment methods again.

9Support

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