Guides
API Reference

Our reference library for integrating with our API

FAQ

Find answers to our most frequently asked questions

Classic Docs

Documentation for our Classic API

Magento 2

From downloading the plugin to requesting your first test payment, learn how to get started with the Checkout.com for Magento 2 plugin.


This guide assumes that you have Magento (the plugin is compatible with version 2.2.8 and above) installed. In addition, you will need to be on a dedicated server, or have the enterprise version of Magento, to use this plugin.

Magento 2 storefront integration

If you're building a storefront on top of a headless Magento 2 backend, install our Magento 2 plugin as set out below, and then follow this guide.


Before you start

Create a test account

If you haven't already, create a test Checkout.com account.

Get your API keys

To set up our Magento 2 plugin, you'll need three API keys: a secret one, a public one, and a private shared one. The first two are generated automatically upon account creation. The last one is generated when you create a webhook for your business.

Webhooks are notifications that we send when an event occurs on your account. For example, when a payment is captured. These are used by the Magento plugin to update the status of an order. Read more about webhooks.

  1. Log in to your test account on the Hub sandbox.
  2. In the left menu, go to Settings > Channels, and make a note of your secret and public API keys.

 Manual webhook creation
  1. Scroll down to the Webhooks section of the page and click New webhook.
  2. Enter the following URL, replacing example.com with the URL of your shop: example.com/checkout_com/webhook/callback. (A webhook URL specific to your installation is available in the Account Settings section of the plugin configuration panel.)

    Correctly configuring your webhooks is important; if they're incorrectly formatted, the plugin will not work.

  3. Select API - v2.0.
  4. Tick Select all, then click Create webhook.
  5. Click on the webhook you just created, and make a note of the private shared API key.

See step 7 in Configure the plugin for automatic webhook registration

Install plugin

There are two ways to install the plugin:

Using Composer 

We recommend this method, as it should install the latest version of the plugin.

  1. Go to the root directory of your Magento 2 server.
  2. Type the following command: 
    composer require checkoutcom/magento2:*
  3. You should get a success message confirming the installation of Checkout.com php sdk and Checkout.com plugin.
  4. The plugin is now installed, but you need to recompile your Magento 2 installation and clear the cache before configuring it. Type the following commands in turn:
    • php bin/magento setup:upgrade
    • rm -rf var/cache var/generation/ var/di
    • php bin/magento setup:di:compile
    • php bin magento cache:clean

Using Magento Marketplace

  1. Purchase the extension from Magento Marketplace (it's free).
  2. Follow the installation instructions on the checkout page.
  3. Once you've installed the extension, log in to your Magento Admin Panel and go to Stores > Configuration > Sales > Payment Methods. If successful, you should now see Checkout.com on the list.

You're now ready to configure the Magento 2 plugin.

Configure the plugin

  1. Log in to you Magento Admin Panel and go to Stores > Configuration > Sales > Payment Methods.
  2. Find the Checkout.com plugin and click Configure.
  3. In this configuration panel, go to Configuration > Global Settings.
  4. Make sure Environment is set to Test so you can start testing card payments.
  5. Select the Payment ActionAuthorize and Capture means that the charge is authorized and captured (i.e., the money due from the customer's account is moved into your account) at the same time. Authorize will only authorize the charge; you have to manually capture the payment yourself. If you're unsure, Authorize and Capture is likely the right choice.
  6. Then go to Account Settings.
  7. Enter your Secret Key and Public Key. If you're testing, make sure you use the API keys from your sandbox Hub account, then click Set Webhooks to automatically register your webhooks in Checkout.com Hub.

  8. Click Save Config.

That's it! You're ready to start testing card payments.

Test your integration

  1. Go to your storefront and add a product to your cart.
  2. Go to your cart and proceed to the checkout.
  3. Enter the required billing details. You can put anything here, though we recommend using a real email address so you can receive the order confirmation.
  4. Select the Pay by Card with Checkout.com method.
  5. Enter the following card details:
    • Number: 4242 4242 4242 4242
    • Expiry date: 12/25
    • CVV: 100
  6. Click Place order, and you will be redirected to the order confirmation page. If you entered a real email address in the billing details, you'll also receive an order confirmation email.
  7. Log in to your Magento Admin Panel.
  8. Go to Sales > Orders. Your test order will be displayed there with a Processing status (or Pending Payment if you choose the Authorize only payment action). This indicates that the payment has been successfully captured. The transaction will also appear in the Payments section of your sandbox Hub account.

You can now either go live as-is or extend your configuration.

Troubleshooting

If this test does not work, first check you have configured your webhooks correctly. For the plugin to work, they must be formatted correctly. If you have configured them properly, check your server; if it's password-protected or it restricts unfamiliar IP addresses, it may be blocking webhook notifications. Contact our Integration team at integration@checkout.com if you need help.

Further testing

You'll find more test cards and a range of scenarios to trigger in our testing guide.

Go live 

If you're happy with the outcome of your testing and want to start taking payments right away, please contact our Sales team in order to move to a live account.

Before you go live, remember to:

  • Switch the environment to Production in the plugin's settings.
  • Update your public, secret and private shared API keys in the plugin's settings with the keys from your live Hub account.
  • Configure the webhook URLs in your live Hub account.

Extend your configuration

You can extend your configuration to add more payment methods, use 3D Secure payments, and more.