# Magento 2 Learn how to get started with the Checkout.com for Magento 2 plugin. > **Note** > > This guide assumes that you have Magento installed. The plugin is compatible with version 2.4.x and later. You also need to be on a dedicated server, or have the enterprise version of Magento, to use this plugin. --- ## Supported features - Manual capture, void, and refund from the [Dashboard](https://dashboard.checkout.com) and the Magento Admin panel - [Frames](https://www.checkout.com/docs/integrate/frames.md) - [Saved cards (stored credit cards)](https://www.checkout.com/docs/payments/store-and-manage-credentials/store-credentials.md) - Invoice generation - [3D Secure 2.0](https://www.checkout.com/docs/risk-management/3d-secure.md) - MOTO payments - Custom order statuses - Webhooks for up-to-date payment statuses - Dynamic descriptors - Multi-store support - Apple Pay fast checkout from the mini cart --- ## Before you start ### Get your API keys To set up the Magento 2 plugin, you need three API keys: - A secret key - A public key - An authorization header key You can create your [secret and public keys](https://www.checkout.com/docs/developer-resources/api/manage-api-keys/api-keys.md) in the Dashboard. The authorization header key is generated when you create a webhook for your business. ### Create a webhook 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. For more information, see [Receive webhooks](https://www.checkout.com/docs/developer-resources/event-notifications/receive-webhooks.md). You can configure a webhook with the default settings directly in the Magento Admin Panel [account settings](#Account_settings). To customize the webhook settings, follow these steps: 1. Sign in to the [Dashboard](https://dashboard.checkout.com). 2. Select _Developers_ in the left navigation bar and open the _Webhooks_ tab. 3. Select _New webhook_. 4. Give the new webhook a name to make it easier to identify in the future. 5. Enter a webhook URL that starts with either `https://` or `http://`. 6. Enter an authorization key. To validate that the webhook is genuine, this is in the header of every webhook we send you. 7. Enter a signature key. Checkout.com generates a hash-based message authentication code (HMAC) from the webhook payload, using the key provided in your workflow's webhook action. The HMAC will be in every notification you receive. 8. You can configure HTTP headers which is included in each webhook notification. You can use this feature to configure a key that you want to provide in your webhook's Authorization HTTP header, enabling you to authenticate requests with your server. 9. Select the events you want to receive webhooks for. There is no limit to the number of events you can select per endpoint. 10. Webhooks are set up at a client level, which means you receive notifications for all entities and processing channels. However, you can filter the updates to specific entities and processing channels. 11. Select _Create webhook_ to publish your endpoint. It goes live from this point onwards. --- ## Install the plugin There are 2 ways to install the plugin: - [Using Composer](#Using_Composer) - [Using Magento Marketplace](#Using_Magento_Marketplace) ### 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. Use one of the following commands: - `composer require checkoutcom/magento2` - `composer require checkoutcom/magento2:` 3. You should get a success message confirming the installation of Checkout.com PHP SDK and our 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 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` ### Using Magento Marketplace 1. Install the plugin from [Magento Marketplace](https://marketplace.magento.com/checkoutcom-magento2.html). 2. Follow the installation instructions on the checkout page. 3. 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. --- ## Configure the plugin 1. Sign in to your Magento Admin Panel and go to _Stores > Configuration > Sales > Payment Methods_. 2. Find the Checkout.com plugin and select _Configure_. ### Global settings 1. In the configuration panel, go to _Configuration > Global Settings_. 2. Make sure _Environment_ is set to _Test_ so you can start testing card payments. 3. 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 only authorizes the charge. You have to capture the payment manually. If you're unsure, _Authorize and Capture_ is likely the right choice. ### Account settings 1. In the configuration panel, go to _Configuration > Account Settings_. 2. Set _Service_ to _NAS_. 3. Enter your _Secret Key_ and _Public Key_. If you're testing, make sure you use the sandbox API keys. 4. In the _Authorization Header Key_ field, copy and paste the authorization header key from the _Developers_ > _Keys_ section of your Dashboard account. 5. Select _Set Webhooks_ to automatically register your webhooks in the Checkout.com Dashboard. 6. Select _Save Config_. --- ## Test your integration 1. Go to your storefront and add a product to your cart. 2. Go to your cart and proceed to checkout. 3. Enter the required billing details. We recommend using a real email address so you can receive the order confirmation. 4. Select _Pay by Card with Checkout.com_. 5. Enter the following card details: - Number – `4242 4242 4242 4242` - Expiry date – Any future date - CVV – `100` 6. Select _Place order_. You're redirected to the order confirmation page. If you entered a real email address in the billing details, you also receive an order confirmation email. 7. Sign in to your Magento Admin Panel. 8. 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](#Go_live) as is or [extend your configuration](#Extend_your_configuration). For test cards and a range of possible scenarios, see [Testing](https://www.checkout.com/docs/developer-resources/testing.md). > **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. If you need help, you can [request support](https://dashboard.checkout.com/support/new?topic=case_account_management_and_access&issue=issue_account_changes). --- ## 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](https://checkout.com/contact-sales) 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. --- ## Extend your configuration 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 can find how to: - [Add more payment methods](#Add_more_payment_methods) - [Enable 3D Secure payments](#Enable_3D_Secure_payments) - [Enable payments with saved cards](#Enable_payments_with_saved_cards) - [Enable MOTO payments](#Enable_MOTO_payments) - [Configure card payment options](#Card_payment_options) - [Configure general payment options](#General_payment_options) - [Manually capture, void and refund payments](#Manually_capture,_void_and_refund_payments) - [Configure order settings](#Order_settings) ### Add more payment methods > **Note** > > To start accepting an alternative payment method, we first need to enable it on your account. Contact your account manager or our [Sales team](https://checkout.com/contact-sales) to get started. We support the following payment methods on Magento 2: - [Apple Pay](https://www.checkout.com/payment-methods/applepay) - [Bancontact](https://www.checkout.com/payment-methods/bancontact) - [Cartes Bancaires](https://www.checkout.com/payment-methods/cartes-bancaires) - [Fawry](https://www.checkout.com/payment-methods/fawry) - [Google Pay](https://www.checkout.com/payment-methods/googlepay) - [iDEAL](https://www.checkout.com/payment-methods/ideal) - [Klarna Debit Risk](https://www.checkout.com/payment-methods/klarna-debit-risk) - [Klarna Payments](https://www.checkout.com/payment-methods/klarna) - [KNET](https://www.checkout.com/payment-methods/knet) - [Mada](https://www.checkout.com/payment-methods/mada) - [PayPal](https://www.checkout.com/payment-methods/paypal) Check the individual payment method pages to see which ones you can support. It depends on your location, as well as the currency and billing address of your customer. #### Enable alternative payments 1. Sign in to your Magento Admin Panel and go to _Stores > Configuration > Sales > Payment Methods_. 2. Find the Checkout.com plugin, select _Configure_ and expand _Alternative Payments_. 3. Specify the _Title_ customers see when they select an alternative payment method. 4. Set _Enable Alternative Payments_ to _Yes_. 5. Select the payment methods you want to support. 6. Select _Save Config_. #### Apple Pay > **Information** > > See our [Apple Pay documentation](https://www.checkout.com/docs/payments/payment-methods/apple-pay.md) for more information. 1. Sign in to your Magento Admin Panel and go to _Stores > Configuration > Sales > Payment Methods_. 2. Find the Checkout.com plugin, select _Configure_ and expand _Apple Pay Payments_. 3. Specify the _Title_ customers see when they select this payment method. 4. Set _Enable Apple Pay_ to _Yes_. 5. 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_. 6. 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_. 7. Enter your _Merchant ID_. You can find this in your Apple Developer account. 8. 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. 9. 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. 10. Enter your processing certificate password, if you have one. 11. Choose the appearance of the Apple Pay button. See the [Apple Developer docs](https://developer.apple.com/design/human-interface-guidelines/buttons) for more detail. 12. Under _Supported Networks_, select the card networks you want to allow through Apple Pay. 13. Under _Merchant Capabilities_, select the type of cards you want to allow. 14. Select _Save Config_. #### Google Pay > **Information** > > See our [Google Pay documentation](https://www.checkout.com/docs/payments/payment-methods/google-pay.md) for more information. 1. Sign in to your Magento Admin Panel and go to _Stores > Configuration > Sales > Payment Methods_. 2. Find the Checkout.com plugin, select _Configure_ and expand _Google Pay Payments_. 3. Specify the _Title_ customers see when they select this payment method. 4. Set _Enable Google Pay_ to _Yes_. 5. If you want to enable 3DS for Google Pay, set _Use 3D Secure_ to _Yes_. 6. Select your Google Pay environment – either _Test_ or _Production_. Note: This is not the same as the Checkout.com environment setting. 7. 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. 8. Choose the appearance of the Google Pay button. See the [Google Pay docs](https://developers.google.com/pay/api/web/guides/brand-guidelines) for more detail. 9. Under _Supported Networks_, select the card networks you want to allow through Google Pay. 10. Select _Save Config_. ### Enable 3D Secure payments > **Note** > > If you enable this feature, every transaction triggers a 3D Secure (3DS) check. If you only want to trigger 3DS authentication for certain transactions, contact your account manager. 1. Sign in to your Magento Admin Panel and go to _Stores > Configuration > Sales > Payment Methods_. 2. Find the Checkout.com plugin, select _Configure_ and expand _Card Payments_. 3. Make sure _Enable Card Payments_ is set to _Yes_. 4. Set _Use 3D Secure_ to _Yes_. 5. Select whether you want to attempt non-3D Secure transactions. If you select _Yes_, any cards that do not support 3DS go through without a 3DS check. If you select _No_, cards that do not support 3DS are blocked. 6. Select _Save Config_. ### Enable payments with saved cards 1. Sign in to your Magento Admin Panel and go to _Stores > Configuration > Sales > Payment Methods_. 2. Find the Checkout.com plugin, select _Configure_ and expand _Card Payments_. 3. 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. 4. Next, expand _Saved Card Payments_. 5. Set _Vault Enabled_ to _Yes_. 6. Specify the _Title_ customers see when they choose to pay with a saved card. 7. Set _Use 3D Secure_ to _Yes_ if you want saved cards to go through 3D Secure authentication. 8. 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 go through without a 3DS check. If you select _No_, saved cards that do not support 3DS are blocked. 9. 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. 10. Select _Save Config_. ### Enable MOTO payments These settings allow the administrator of your account to carry out mail order / telephone order (MOTO) payments on your customers' behalf. 1. Sign in to your Magento Admin Panel and go to _Stores > Configuration > Sales > Payment Methods_. 2. Find the Checkout.com plugin, select _Configure_ and expand _MOTO Payments_. 3. Set _MOTO Enabled_ to _Yes_ if you want to allow your administrator to carry out MOTO payments. 4. Specify what _Title_ you want your customers to see when they select the MOTO payment option. 5. Set _Saved Cards Enabled_ to _Yes_ if you want to allow your administrator to make MOTO payments using customers' saved cards. 6. Select _Save Config_. ### Card payment options 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_. #### Payment option title Enables you to specify what title the customer sees when they choose to pay by card. #### Display card icons Set to _Yes_ if you want to display card scheme logos to customers, and then select the particular scheme logos you want to display. #### Payment form layout 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](https://www.checkout.com/docs/integrate/frames/frames-customization-guide.md) for more information. #### Payment form styles 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](https://www.checkout.com/docs/integrate/frames/frames-customization-guide.md) for more information. ### General payment options 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_. #### Payment action 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 need to manually capture the payment afterward. #### Capture time 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). #### Dynamic descriptor 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. 1. Set _Enable Dynamic Descriptor_ to _Yes_ if you want to send this extra information. If you do not enable this, the customer only sees your merchant name as it appears in your Dashboard account. 2. Specify the _Descriptor Name_. This is the first line of the descriptor, usually your merchant name. You can use up to 25 characters. 3. 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. ### Manually capture, void and refund payments As well as doing so through the Dashboard, you can also manually capture, void, and refund payments from the Magento Admin Panel. These actions appear in both Magento and the Dashboard. #### Manually capture payment 1. Sign in to your Magento Admin Panel and go to _Stores > Configuration > Sales > Payment Methods_. 2. Find the Checkout.com plugin, select _Configure_ and expand _Configuration > Global Settings_. 3. Make sure _Payment Action_ is set to _Authorize_. 4. 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_. 5. Select _Invoice_. 6. Select _Submit Invoice_ at the bottom of the page to complete and capture the payment. #### Void payment You can only void payments that have been authorized but not yet captured. 1. Sign in to your Magento Admin Panel and go to _Stores > Configuration > Sales > Payment Methods_. 2. Find the Checkout.com plugin, select _Configure_ and expand _Configuration > Global Settings_. 3. Make sure _Payment Action_ is set to _Authorize_. 4. 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. 5. Select _Void_ to void the payment. #### Refund a 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 does not record the refund in your Dashboard account. 1. Once you've created an order, sign in to your Magento Admin Panel and find the order in _Sales > Orders_. 2. If the payment was not captured automatically on authorization, capture the payment now. A captured payment has a `Processing` status. 3. Select _View_ to open the order. 4. Select _Invoices_, then select _View_ to open the invoice. 5. Select _Credit Memo_. 6. Select the products you want to refund and select _Refund_ (not _Refund Offline_). ### Order settings 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 > Order Settings_. #### Action on failed payment Select the action you want to be taken on orders with failed payments. We recommend you choose _Cancel the order_. This cancels 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 deletes any trace of the failed order, leaving no record of it. #### Order confirmation email Select at what point you want to send the customer an order confirmation email. _Authorize_ sends an order confirmation email to the customer as soon as the payment is authorized. _Authorize and Capture_ sends it only after the payment has been both authorized and captured. #### Order statuses 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.