Dokumentation

1Shopify Integration

Shopify is a Canadian e-commerce company headquartered in Ottawa, Ontario, that develops computer software for online stores and retail point-of-sale systems. We built an integration into Shopify’s Payment gateway that lets you process transactions in your Store. The following documentation will describe you step-by-step how you can integrate the payment gateway into your store.

2Use the Setup Assistant

The easiest way to connect your Shopify store is to use our Setup Assistant that you can access directly from your space. Alternatively you can launch the Boarding Assistant also here.

Create Integration
Figure 1. The easiest way to connect your Shopify Store is to use the Setup Assistant which will install the app and connect the platform to your store.

The Setup Assistant will then connect your Shopify Store to the platform. All you need to do now is to install the desired payment gateways as described further below in the section Adding the Payment Gateway.

3Connect Your Shopify Store Manually

If you do not want to use the Setup Assistant please follow the next steps described below.

3.1Activate the Shopify Feature

It is possible that the Shopify menu is not available in your space inside the application. In this case you have to first navigate to the feature list and activate the Shopify Feature Space > Features. Here you find the Shopify Icon. Click on the "Activate" button.

Note
In case you do not see any Shopify Logo there it can be that the feature is not activated in your subscription and you need to change the product. In this case you navigate to Account > (Select your Account) > Billing. Here you can select to change your subscription.

3.2Create a Shopify Integration

As next step you have to create your Shopify Integration. For this navigate to Space > Shopify and create your integration. Make sure you set a name and you type name used in the Shopify admin URL: [shopName].myshopify.com.

3.3Shopify Shop Identifer and Securiy Token

After you stored your Integration you are presented with the Shopify credentials that you put into the configuration field of the gateway that you just added.

Create Integration
Figure 2. You will be presented with the Shopify gateway credentials for your integration.

Write these credentials down or open a new window tab. You will need them later when the payment methods inside Shopify have to be configured. The credentials will only be shown once.

3.4Generate New Shopify Shop Identifier or Token

In case you have to create new credentials for your already existing integration you have to go to Space > Shopify and click to the lock symbol. This will take you to the overview of active Shopify Integration Security Tokens. Click on Generate New Security Token to create new credentials.

Note
You can only have two active tokens. Otherwise you have to disable not used tokens here.
Add Gateway
Figure 3. Add the gateway to your Shopify Store

3.5Install the Shopify App

You can now close the window with the Shopify credentials and click on Install Shopify App by opening your Shopify Integration we just created. This will forward you to your Shopify store. Once you are granted the permission you are able to use the integration.

The Shopify App makes sure that the transaction state in your store and in the platform are in sync and that the line items are transmitted.

4Adding the Payment Gateway

In order to add the payment method to Shopify you will now have to install the different payment methods in your store. This needs to be done independently depending on how you connected your store (using the setup assistant or manually).

Payment Pre-selection in your Shopify Checkout
Figure 4. This screenshot shows the payment pre-selection where the payment methods are shown individually in your checkout.

Shopify only accepts a few pre-installed gateways for each country. In order to allow you to process all you desired brands you will have to install the different payment methods individually by clicking on the links below. The link takes you to the login page of Shopify to install the payment gateway in your admin panel.

Once you clicked on the link you will be prompted to login to your store and asked if you want to add the payment method in your store. Click the add button in order to proceed.

Once the Gateway has been confirmed it is visible in your Shopify Store Settings > Payment providers in the section Alternative Payments or Credit Cards.

Add Gateway
Figure 5. Add the gateway to your Shopify Store

Adding the payment method individually to your Shopify store will result in the pre-selection of the payment method on the your payment page.

4.1Add Identifier and Security Token

Copy now the credentials from your Shopify integration into the corresponding configuration field for the Shop Identifier and the Security Token for every payment method.

Add Gateway
Figure 6. Select the gateway and copy the credentials for your Shopify integration into the fields.

5Payment Processing

We provide two different ways how the payment processing is done:

  • With the default Integrated Payment Form the entry of payment details happens in your checkout after the order is confirmed by your customer. There is not redirection to the payment page.

  • With the Payment Page Integration the customer is redirected after the order is confirmed to the payment page to finalize the payment.

Find out more how those two modes can be enabled:

5.1Integrated Payment Form

The default integration is the integrated payment form where the customer will enter the credit card details in a form that is located in your Shopify Checkout after he has confirmed the order. This allows best in class user experience.

Note
For this to work you have to make sure that the app proxy path /apps/checkout/ is not taken by another app. Otherwise get in touch with us or disable the other plugin.

The integrated payment form will display the payment form directly in your Shopify Checkout.

Integrated Payment Form
Figure 7. The integrated payment form will display the payment form directly in your Shopify Checkout.

In order to activate this feature, make sure that in your Shopify Installation you have set the Integrated Payment Form Option to on.

Make sure the integrated payment form is set to on.

Settings of the Integrated Payment Form
Figure 8. The integrated payment form will display the payment form directly in your Shopify Checkout.

If you are using CloudFlare in your store:

To load the integrated payment form in Shopify, we use a so called App Proxy, which means that Shopify connects to our server and we then return the payment form. For this we use CloudFlare in the background. If you are also using CloudFlare in your store CloudFlare believes that the traffic is routed twice by CloudFlare, which is not allowed.

To solve the issue you can apply one of the following solutions:

  • Disable CloudFlare for your Shopify shop.

  • Disable the 'Integrated Payment Form' in the Shopify integration in your space.

  • Disable URL redirects in Shopify. URL redirects are used to redirect traffic from one web page to another. This can be done under the domain settings within your Shopify store.

5.2Payment Page (redirection)

In this scenario your client will be redirected to the payment page to process the payments. This is the backup integration if you set the Integrated Payment Form to off.

6Configure Your Processor

In order to accept payments over the configured gateway you have to make sure that you configured your processor, payment method and connector correctly. Manuals on how the payment processor needs to be configured can be found on the Processor List.

7State graph

The Payment Process 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 Shopify configuration. An overview about the states and the payment processes can be found in the Payment Documentation.

In the following section we provide you an overview about how the transaction states are mapped into the Shopify State graph for orders.

7.1State mapping of Shopify orders

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

state-graph
Figure 9. Transaction state graph of a Shopify transaction.

8Transaction management

You can capture, cancel and refund transactions directly from within the Shopify backend. Please note if you refund, void or capture transactions inside the platform the events will not be synchronized into Shopify.

8.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 complete a transaction in Shopify, open the order and click on the Capture Payment button.

This will finalize the order and it can no longer be changed.

Note
When the completion is pending in the platform the order will stay in the authorized state in Shopify.
capture-transaction
Figure 10. Capture a 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 possible, 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 the platform and in Shopify. 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 the platform and into Paid state in Shopify. You can now start the fulfillment process.

8.2Void a transaction

In order to void a transaction, click on the More actions button and then on the Cancel order button.

Note
You can only void transactions that are not yet completed.
void-transaction
Figure 11. Void a Transaction.

8.3Refund a transaction

You have the possibility to refund already completed transactions. In order to do so, open the captured order. By clicking on Refund the window for refunds will show.

refund-transaction
Figure 12. Refund a Transaction.
Note
You have to make sure that the connector you processed this payment with supports the refund feature. In order to check that have a look at the processor list and check the connector of a processor.
feature-refund
Figure 13. See the example of an AMEX connector that supports Refunds.

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

refund-transaction
Figure 14. Refund a Transaction.

You can carry out as many individual refunds as you wish until you have reached the quantity of the original order.

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

8.4On hold orders

As long as the delivery should not be done the state of the order will be in Authorized. This happens when the transaction has not reached the fulfill state in the platform yet.

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, we 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.

9Matching Shopify Transactions in your Processor

If you want to match your Shopify Order with the payments in your processors this is not so straight forward. The main problem is that by the time we have to create the transaction at the processor we do not have the Shopify Transaction and Order Name. This is why we have to transmit the Checkout ID.

Nonetheless, you are able to match the transactions via the Shopify Transaction List in your space. The list provides you with the mapping of Checkout ID which equals the merchantReference in your processor and the OrderName which is visible in your Shopify Store.

shopify-transaction-list
Figure 15. The Shopify Transaction Table provides you the mapping for the orderName and checkoutId.
Note
It is necessary that you install our app in order to have this details. You can also export this list by clicking on the export icon in the table.

10One Click Payments with Shopify

The application supports the option to securely store the payment information of your customer. This will increase your conversion for merchants that re-visit your store as they do not have to enter payment information again.

10.1Activate the One-Click Mode

In order to create token you will have to configure your payment method as described in the Tokenization Documentation.

shopify-transaction-list
Figure 16. Let your merchants choose from a previously stored token.

10.2Configure Shopify Account Creation

As the token is tied to a customerId the stored token will only be visible for the merchant that creates an account in your Shopify store. This is why you will have to make sure that the creation of accounts is enabled. If you want to make sure that the merchant token will be displayed we even suggest to force the account creation in Shopify.

Navigate in your Shopfiy backend to Settings > Checkout and set the account selection to Accounts are required or Accounts are optional.