Magento 2

Last updated: November 28, 2024

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

Note

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

Manual capture, void, and refund from the Dashboard and the Magento Admin panel
Frames
Saved cards (stored credit cards)
Invoice generation
3D Secure 2.0
MOTO payments
Custom order statuses
Webhook notifications for up-to-date payment statuses
Dynamic descriptors
Multi-store support
Apple Pay fast checkout from the mini cart

To set up our Magento 2 plugin, you'll need 3 API keys: a secret key, a public key, and an authorization header key. You can create your secret and public keys in the Dashboard. The authorization header key 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.

You can configure a webhook with the default settings directly in the Magento Admin Panel account settings. If you'd like to customize the webhook settings, follow these steps:

Sign in to the Dashboard.
Select the Developers icon in the top navigation bar and open the Webhooks tab.
Select New webhook.
Give the new webhook a name to make it easier to identify in the future.
Enter a webhook URL that starts with either https:// or http://.
Enter an authorization key. To validate that the webhook is genuine, this will be in the header of every webhook notification we send you.
Enter a signature key. Checkout.com generates a hash-based message authentication code (HMAC) from the webhook notification contents, using the key provided in your workflow's webhook action. The HMAC will be in every notification you receive.
You can configure HTTP headers which will be included in each webhook notification. You can use this feature to configure a key that you want to provide in your webhook notifications' Authorization HTTP header, allowing you to authenticate requests with your server.
Select the events you want to receive webhooks for. There is no limit to the number of events you can select per endpoint.
Webhooks are set up at a client level, which means you will receive notifications for all entities and processing channels. However, you can filter the updates to specific entities and processing channels.
Select Create webhook to publish your endpoint. It will be live from this point onwards.

There are 2 ways to install the plugin:

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

Go to the root directory of your Magento 2 server.
Use one of the following commands:
- composer require checkoutcom/magento2
- composer require checkoutcom/magento2:<VERSION_NUMBER>
You should get a success message confirming the installation of Checkout.com PHP SDK and our plugin.
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 order:
1. php bin/magento setup:upgrade
2. rm -rf var/cache var/generation/ var/di
3. php bin/magento setup:di:compile
4. php bin magento cache:clean

Install our plugin for free from Magento Marketplace.
Follow the installation instructions on the checkout page.
Once you've installed the extension, sign 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.

Sign in to your Magento Admin Panel and go to Stores > Configuration > Sales > Payment Methods.
Find the Checkout.com plugin and select Configure.

In the configuration panel, go to Configuration > Global Settings.
Make sure Environment is set to Test so you can start testing card payments.
Select the Payment Action:

The Authorize and Capture option means that the charge is authorized and captured (that is, the money due from the customer's account is moved into your account) at the same time.
The Authorize option will only authorize the charge. You'll have to capture the payment manually.

If you're unsure, Authorize and Capture is likely the right choice.

In the configuration panel, go to Configuration > Account Settings.
Set Service to NAS.
Enter your Secret Key and Public Key. If you're testing, make sure you use the sandbox API keys.
In the Authorization Header Key field, copy and paste the authorization header key from the Notifications section of your Dashboard account.
Select Set Webhooks to automatically register your webhooks in the Checkout.com Dashboard.
Select Save Config.

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

Go to your storefront and add a product to your cart.
Go to your cart and proceed to checkout.
Enter the required billing details. We recommend using a real email address so you can receive the order confirmation.
Select Pay by Card with Checkout.com.
Enter the following card details:
- Number: 4242 4242 4242 4242
- Expiry date: any future date
- CVV: 100
Select Place order. You'll 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.
Sign in to your Magento Admin Panel.
Go to Sales > Orders. Your test order is displayed with a Processing status (or Pending Payment if you choose the Authorize payment action). The status indicates that the payment has been successfully captured. The transaction also appears in the Payments > Processing > All Payments section of your Test Dashboard.

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

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

Note

If this test does not work, first check you have configured your webhooks 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 Support team at [email protected] if you need help.

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.

Information

Before you go live, remember to:

Switch the Environment to Production in the plugin's settings.
Replace the sandbox API keys in the plugin's settings with the production API keys.
Configure the webhook URLs in your live Dashboard account.

There are a number of ways you can extend your Magento 2 integration so that it suits all your business needs.

In this section, you'll find how to:

Note

In order to start accepting an alternative payment method, we first need to enable it on your account. Please contact your Account Manager or our Sales team to get started.

We support the following payment methods on Magento 2:

Check the individual payment method pages to see which ones you can support. It will depend on your location, as well as the currency and billing address of your customer.

Sign in to your Magento Admin Panel and go to Stores > Configuration > Sales > Payment Methods.
Find the Checkout.com plugin, select Configure and expand Alternative Payments.
Specify the Title customers will see when they select an alternative payment method.
Set Enable Alternative Payments to Yes.
Select the payment methods you want to support.
Select Save Config.

Information

See our Apple Pay documentation for more information.

Sign in to your Magento Admin Panel and go to Stores > Configuration > Sales > Payment Methods.
Find the Checkout.com plugin, select Configure and expand Apple Pay Payments.
Specify the Title customers see when they select this payment method.
Set Enable Apple Pay to Yes.
If you want to add an Apple Pay button to your shopping basket page, so your customers can choose to check out via Apple Pay from their cart, set Enable Apple Pay On Cart Page to Yes.
If you want to allow your customers to check out with Apple Pay from the mini cart, set Enable Apple Pay on MiniCart to Yes.
Enter your Merchant ID. You can find this in your Apple Developer account.
Enter the absolute path of your payment processing certificate (for example, mywebsite/app/checkout/certificate.pem). To get this, find your certificate (a .pem file) in your Apple Developer account and then upload it to your server.
Enter the absolute path of your merchant identity certificate key (for example, mywebsite/app/checkout/certificate_key.key). To get this, find your key (a .key file) in your Apple Developer account and then upload it to your server.
Enter your processing certificate password, if you have one.
Choose the appearance of the Apple Pay button. See the Apple Developer docs for more detail.
Under Supported Networks, select the card networks you want to allow through Apple Pay.
Under Merchant Capabilities, select the type of cards you want to allow.
Select Save Config.

Information

See our Google Pay documentation for more information.

Sign in to your Magento Admin Panel and go to Stores > Configuration > Sales > Payment Methods.
Find the Checkout.com plugin, select Configure and expand Google Pay Payments.
Specify the Title customers see when they select this payment method.
Set Enable Google Pay to Yes.
If you want to enable 3DS for Google Pay, set Use 3D Secure to Yes.
Select your Google Pay environment – either Test or Production. Note: This is not the same as the Checkout.com environment setting.
Enter your Merchant ID. You can find this in your Google payments profile. If testing, use 01234567890123456789. Note: Make sure you use the right merchant ID for your chosen Google Pay environment.
Choose the appearance of the Google Pay button. See the Google Pay docs for more detail.
Under Supported Networks, select the card networks you want to allow through Google Pay.
Select Save Config.

Note

If you enable this feature, every transaction will trigger a 3D Secure (3DS) check. If you only want to trigger 3DS authentication for certain transactions, contact your Account Manager.

Sign in to your Magento Admin Panel and go to Stores > Configuration > Sales > Payment Methods.
Find the Checkout.com plugin, select Configure and expand Card Payments.
Make sure Enable Card Payments is set to Yes.
Set Use 3D Secure to Yes.
Select whether you want to attempt non-3D Secure transactions. If you select Yes, any cards that do not support 3DS will go through without a 3DS check. If you select No, cards that do not support 3DS will be blocked.
Select Save Config.

Sign in to your Magento Admin Panel and go to Stores > Configuration > Sales > Payment Methods.
Find the Checkout.com plugin, select Configure and expand Card Payments.
Set Save Card Option to Yes if you want to allow your customers to save their cards for future payments. They can then use the same card on your website without re-entering the details.
Next, expand Saved Card Payments.
Set Vault Enabled to Yes.
Specify the Title customers see when they choose to pay with a saved card.
Set Use 3D Secure to Yes if you want saved cards to go through 3D Secure authentication.
Select whether or not you want to attempt non-3D Secure transactions for saved cards. If you select Yes, any saved cards that do not support 3DS will go through without a 3DS check. If you select No, saved cards that do not support 3DS will be blocked.
Set Require CVV for saved cards to Yes if you want the customer to enter the three (or four) digit CVV when they pay with a saved card. This provides additional security against fraud. Select No if you're happy for the customer to pay with a saved card without entering the card's CVV.
Select Save Config.

These settings allow the administrator of your account to carry out mail order / telephone order (MOTO) payments on your customers' behalf.

Sign in to your Magento Admin Panel and go to Stores > Configuration > Sales > Payment Methods.
Find the Checkout.com plugin, select Configure and expand MOTO Payments.
Set MOTO Enabled to Yes if you want to allow your administrator to carry out MOTO payments.
Specify what Title you want your customers to see when they select the MOTO payment option.
Set Saved Cards Enabled to Yes if you want to allow your administrator to make MOTO payments using customers' saved cards.
Select Save Config.

To find these settings, sign in to your Magento Admin Panel and go to Stores > Configuration > Sales > Payment Methods. Find the Checkout.com plugin, select Configure and expand Card Payments.

Allows you to specify what title the customer will see when they choose to pay by card.

Set to Yes if you want to display card scheme logos to customers, and then select the particular scheme logos you want to display.

Select your preferred layout for the payment form. Single iframe displays a one-line payment form. Multiple iframes displays a payment form of three fields. See our Frames customization guide for more information.

Allows you to customize the payment form's look and feel. You can add CSS styles in JSON format to alter the form's appearance. For example: {"base":{"color":"blue","fontSize":"18px"}}. See our Frames customization guide for more information.

To find these settings, sign in to your Magento Admin Panel and go to Stores > Configuration > Sales > Payment Methods. Find the Checkout.com plugin, select Configure and expand Configuration > Global Settings.

If you want to manually capture payments, rather than have payments automatically captured (the Authorize and Capture option), set Payment Action to Authorize. Payments will now be authorized, but you will need to manually capture the payment afterward.

If you set the Authorize and Capture as the Payment Action, you can use the Capture Time setting to specify the delay (in hours) before the payment is captured. For example, 1.500 for capture after 1 hour and 30 minutes; 0.02 for capture after 72 seconds. We do not recommend setting a value lower than 0.02 (72 seconds).

This is an extra field that you can send to the issuer, appearing on the customer's bank statement as an additional description of the payment.

Set Enable Dynamic Descriptor to Yes if you want to send this extra information. If not enabled, the shopper will just see your merchant name as it appears in your Dashboard account.
Specify the Descriptor Name. This is the first line of the descriptor, usually your merchant name. You can use up to 25 characters.
Specify the Descriptor City. This is the second line of the descriptor, usually the city of your merchant address. You can use up to 13 characters.

As well as doing so through the Dashboard, you can also manually capture, void, and refund payments from the Magento Admin Panel. These actions will show in both Magento and the Dashboard.

Sign in to your Magento Admin Panel and go to Stores > Configuration > Sales > Payment Methods.
Find the Checkout.com plugin, select Configure and expand Configuration > Global Settings.
Make sure Payment Action is set to Authorize.
Once you've created an order, find it in Sales > Orders in your Magento Admin Panel. It should have a Pending Payment status. Select View.
Select Invoice.
Select Submit Invoice at the bottom of the page to complete and capture the payment.

You can only void payments that have been authorized but not yet captured.

Sign in to your Magento Admin Panel and go to Stores > Configuration > Sales > Payment Methods.
Find the Checkout.com plugin, select Configure and expand Configuration > Global Settings.
Make sure Payment Action is set to Authorize.
Once you've created an order, find it in Sales > Orders in your Magento Admin Panel. It should have a Pending Payment status. Select View to open the order.
Select Void to void the payment.

If refunding through Magento, we recommend you do so through the invoice for the order, rather than selecting Credit Memo from the order view. The latter only gives you a Refund offline option, which will not record the refund in your Dashboard account.

Once you've created an order, sign in to your Magento Admin Panel and find the order in Sales > Orders.
If the payment was not captured automatically on authorization, capture the payment now. A captured payment will have a Processing status.
Select View to open the order.
Select Invoices, then select View to open the invoice.
Select Credit Memo.
Select the products you want to refund and select Refund (not Refund Offline).

Select the action you want to be taken on orders with failed payments. We recommend you choose Cancel the order. This will cancel the order where the payment fails, but still record it so you have a trace of all failed orders. If you choose Delete the order, it will delete any trace of the failed order, leaving no record of it.

Select at what point you want to send the customer an order confirmation email. Authorize will send an order confirmation email to the customer as soon as the payment is authorized. Authorize and Capture will send it only after the payment has been both authorized and captured.

These settings allow you to edit the order statuses in line with the status of the payment. They are automatically set to Magento's default values, so be aware that editing them may cause problems with the order flow.

Note

Supported features

Before you start

Get your API keys

Create a webhook

Install the plugin

Using Composer

Using Magento Marketplace

Configure the plugin

Global settings

Account settings

Test your integration

Note

Go live

Information

Extend your configuration

Add more payment methods

Note

Enable alternative payments

Apple Pay

Information

Google Pay

Information

Enable 3D Secure payments

Note

Enable payments with saved cards

Enable MOTO payments

Card payment options

Payment option title

Display card icons

Payment form layout

Payment form styles

General payment options

Payment action

Capture time

Dynamic descriptor

Manually capture, void and refund payments

Manually capture payment

Void payment

Refund a payment

Order settings

Action on failed payment

Order confirmation email

Order statuses