Magento 2 (Adobe Commerce) Setup
Learn how to connect your Magento 2 account to BlueSnap for a unified shopping cart and payment gateway solution.
Magento, now Adobe Commerce, provides a flexible, e-commerce platform on which merchants can create and manage their online stores. By connecting to BlueSnap, you can securely process global credit and debit card payments right from your checkout page; shoppers never have to leave your site. Additionally, you can take advantage of BlueSnap’s comprehensive reporting capabilities to better understand your business.
Supported Features
3D Secure
Auth/Capture and Separate Auth and Capture
Chargeback Management
Fraud Prevention
Built-in Fraud Protection with optional UDFs and Risk Management
Enhanced fraud using Device Data Collector
Hosted Payment Fields
Multiple Currencies
Partner Sandbox Testing
Payment Analytics and Reporting
Payment Methods: ACH/ECP, Apple Pay, Credit/Debit Cards, Google Pay, iDEAL, Latam Local Card Processing, Sofort and Splitit
Payment Optimization
Subscriptions
Vaulted Shoppers
Requirements
- Magento 2.4.x Commerce (formerly Enterprise)
- Magento 2.4.x Opensource (formerly Community)
- Adobe Commerce 2.4x
We recommend:
- PHP 8.2 for Magento 2.4.6
- PHP 8.1 for Magento 2.4.4+
- PHP 7.4 for Magento 2.4.0-2.4.3-p2
Magento and BlueSnap Accounts
You must have accounts at both Magento (Adobe Commerce) and BlueSnap to proceed.
If you need a Magento account, go to the Magento website to sign up.
If you need a BlueSnap account, go to the BlueSnap website to get started.
Magento Software
This guide assumes that you already have the Magento software installed and uploaded to your server. For Magento's system requirements, refer to the Magento documentation.
HTTPS Configuration
BlueSnap requires a secure connection to process payments. You must ensure that your domain is SSL certified and SSL is enabled for Magento. (Step 4: Enable SSL explains how.)
Supported Currencies
BlueSnap supports the currencies listed here. We recommend configuring your store to only accept currencies supported by BlueSnap.
Supported Countries
BlueSnap supports the countries listed here. If a shopper is located in one of these supported countries, they will be able to purchase with the BlueSnap payment module.
PCI Compliance
A PCI compliance of SAQ-A is required.
Magento 2 Setup
Step 1: Configure your BlueSnap account settings
Before you install the BlueSnap extension in Magento, complete these steps in your Merchant Portal for production or sandbox.
-
Get your BlueSnap API credentials and define the authorized IP addresses for your server production environment to be used for API calls. Both of these actions are performed on the same page; for instructions click here.
-
To get paid, you need to configure your payout settings. Refer to Payout for more information.
Step 2: Install and upload the BlueSnap extension
The BlueSnap extension is available from Magento for free. Follow the Adobe Commerce steps here to learn how to install an extension.
Note: The key for the BlueSnap module is bluesnap/m2-module-payment.
Step 3. Configure the BlueSnap extension
To configure the BlueSnap Extension, you must be logged in to your store as an admin.
-
Go to Stores > Configuration > Sales > Payment Methods. If the installation was successful, you see the new BlueSnap Credit/Debit Card Payments section. Click this section to expand it.
-
Configure the following settings.
| Setting | Description |
|---|---|
| Enable this Solution | Select Yes to enable the BlueSnap extension. This means that BlueSnap Credit/Debit Cards appears as a payment option during checkout. |
| Enable Vaulted Shoppers | _ Select Yes to let logged-in shoppers store their credit card details for future purchases. They can manage their information from their My Account area. _ Select No to disable this option. If you are selling subscriptions, this must be set to Yes. |
| IPN Configuration | Copy the URL from this section and use it for the IPN Setup section below. |
| Enable 3D secure | _ If you want to offer 3‑D Secure, contact BlueSnap Merchant Support and ask for 3‑D Secure to be enabled for your account. After that is done, you can select Yes here to activate 3‑D Secure. For more information on 3‑D Secure, refer to our 3‑D Secure Guide. (Note: This link opens in a new tab.) _ Select No if you do not want to use 3‑D Secure. |
| Enable Dynamic Currency Conversion (DCC) | The default selection is “No”, as we follow Magento’s default currency configuration. Magento provides three types of currencies: - Base currency (for your store) - Display currency (what shoppers see) - Allowed currency (select same as Base currency) To provide the best experience for your shoppers, you should configure a base currency for each of your stores/websites. The display currency and allowed currency are set to allow your shoppers to see prices in their specific currency. However, if the display or allowed currency differs from the store's base currency, the shopper will be charged in the base currency and not the allowed or displayed currency. For subscription products, if the display or allowed currency differs from the store's base currency, prices will be displayed and stored incorrectly. It is best practice to ensure the configured currencies match. If you plan to offer multiple currencies, Magento's best practice is to set a store for each currency you plan to offer, and then use geo-location to direct the shopper to the proper store. |
| Mode | _ Select Sandbox to work with your BlueSnap sandbox account for testing purposes. _ Select Production to work with your BlueSnap production account. >Note: You should set this field to Production once you are ready to start processing live transactions. |
| Payment Action | _ Select Authorize Only to only run an authorization on the card to ensure there is enough available credit; however, payment is not processed until the capture step. We recommend that you use this option if you plan to deliver your products at a later date. See Capture Payments to learn how to manually capture the order payment later. _ Select Authorize and Capture to authorize a transaction and capture the payment in the same step. We recommend you use this option if you sell digital goods or products that are in stock and are ready to be shipped immediately after purchase. |
| Order State for Void | Select an option from the dropdown. This will determine the state of the order when a transaction is void. |
| Soft Descriptor | Enter a string, no more than 20 characters in length. This descriptor appears on the shopper's billing statement to help them identify the purchase. >Note: Do not use BLS* in your soft descriptor; the asterisk (*) is an unrecognized character in Magento. |
| Sort Order | Enter an integer to alter the positioning of the BlueSnap Credit/Debit Cards payment method above or below other methods. The payment method with the smallest sort order appears at the top of the checkout form. |
| Title | By default, this field displays Credit/Debit Cards. This label is displayed to the shopper when they choose a payment option during checkout. |
| Payment from Applicable Countries | _ Select All Allowed Countries to allow BlueSnap to be listed as a payment option for any country configured in Magento. _ Select Specific Countries to restrict the BlueSnap payment method to only a specified list of shopper shipping countries. If the shopper's shipping country is not one of the countries you specify in this setting, BlueSnap is not an available payment method. (Available countries are configured in the next setting.) |
| Payment from Specific Countries | If Specific Countries was selected, then this section is applicable. Select the shipping countries for which you want BlueSnap to be an available payment method. >Note: To select multiple countries, hold down either the CTRL key (PCs) or Apple/Cmd key (Macs) while you select the countries. |
| API User Key (Sandbox) and API Password (Sandbox) | Enter your API user key and password for your BlueSnap sandbox account. |
| API User Key (Production) and API Password (Production) | Enter your API user key and password for your BlueSnap production account. >Note: Be sure to enter production API credentials to start processing live transactions. |
| Seller ID (Sandbox) | Enter your merchant ID number from your BlueSnap merchant account (Sandbox). |
| Seller ID (Production) | Enter your merchant ID number from your BlueSnap merchant account (Production). |
| Enterprise Site ID | Site ID must match exactly as it is configured in the Kount Portal. |
| Debug | _ Select Yes to have communications between Magento and BlueSnap recorded in the var/log/payment.log file of your Magento root. We recommend using this option during the development of your site or if you are experiencing any problems._ Select No to opt out of logging communications in the payment.log folder. >Note: Errors are reported in the var/log/system.log file even if Debug is set to No. |
| Error Email Recipient | Enter an email address to which messages are sent if a transaction error occurs. |
| IPN IP Whitelist (Sandbox) | By default, this field contains IP addresses from which you receive IPN/webhooks keeping you informed of activity in your sandbox account. >Note: In the future, BlueSnap may ask you to add or update IP addresses in this setting. |
| IPN IP Whitelist (Production) | By default, this field contains IP addresses from which you receive IPN/webhooks keeping you informed of activity in your production account. >Note: In the future, BlueSnap may ask you to add/update IP addresses in this setting. |
- If the installation was successful, you will also see the BlueSnap ACH section. Click this section to expand it. Configure the following settings.
| Setting | Description |
|---|---|
| Enable this Solution | _ If you want to offer ACH/ECP, contact BlueSnap Merchant Support and ask for ACH/ECP to be enabled for your account. After that is done, you can select Yes here to activate ACH/ECP. For more information on ACH/ECP, refer to our ACH/ECP Guide. (Note: This link opens in a new tab.) _ Select No if you do not want to use ACH/ECP. |
| Title | By default, this field displays ACH Payment. This label is displayed to the shopper when they choose a payment option during checkout. |
| Vault Active | _ Select Yes to let logged-in shoppers store their ACH/ECP details for future purchases. They can manage their information from their My Account area. _ Select No to disable this option. |
- If the installation was successful, you will also see the BlueSnap UI Masking section. Click this section to expand it. Configure the following settings.
| Setting | Description |
|---|---|
| Credit Card Number | If you want to “mask” the value for credit card number during entry, select Yes. Default value is No. |
| Credit Card Validation Number | If you want to “mask” the value for CCV during entry, select Yes. Default value is No. |
- If the installation was successful, you will also see the BlueSnap Errors Configuration section. Click this section to expand it. Configure the following settings.
| Setting | Description |
|---|---|
| Error Display Mode | Select the Error Mode that needs to be displayed to the shopper. |
- If the installation was successful, you will also see the BlueSnap ApplePay section. Click this section to expand it. Configure the following settings.
| Setting | Description |
|---|---|
| Enable this Solution | _ If you want to offer Apple Pay as a payment method for your shoppers, contact BlueSnap Merchant Support and ask for Apple Pay to be enabled for your account. After that is done, you can select Yes here to allow shoppers to pay with Apple Pay. _ Select No if you do not want to present this option. |
| Title | By default, this field displays BlueSnap ApplePay. This label is displayed to the shopper post purchase. |
| Payment Action | _ Select Authorize Only to only run an authorization on the card to ensure there is enough available credit; however, payment is not processed until the capture step. We recommend that you use this option if you plan to deliver your products later. See Capture Payments below to learn how to manually capture the order payment later. _Select Authorize and Capture to authorize a transaction and capture the payment in the same step. We recommend you use this option if you sell digital goods or products that are in stock and are ready to be shipped immediately after purchase. |
| Business Name | Use the same business name shoppers will see when they look for the charge on their bank or credit card statement. For example, "COMPANY, INC." |
| Card Types | Select the card types that should be visible to shoppers during checkout. Visa and MasterCard are enabled by default. |
| Enable Merchant capability | supportsEMV | Select Yes only if you support China Union Pay transactions. Otherwise, select No Note this setting is set to No by default. |
- If the installation was successful, you will also see the BlueSnap Google Pay section. Click this section to expand it. Configure the following settings.
| Setting | Description |
|---|---|
| Enable this Solution | _ If you want to offer Google Pay as a payment method for your shoppers, contact BlueSnap Merchant Support and ask for Google Pay to be enabled for your account. After that is done, you can select Yes here to allow shoppers to pay with Google Pay. _ Select No if you do not want to present this option. |
| Merchant Name | Use the same business name that you will see when you look for the charge on your bank or credit card statement. For example, “COMPANY, INC” |
| Google Merchant Id | * Enter the Google Business Merchant Id created for your business |
| Payment Action | Select Authorize Only to only run an authorization on the card to ensure there is enough available credit (payment is not processed until the capture step). We recommend that you use this option if you plan to deliver your products later. See Capture Payments below to learn how to manually capture the order payment later. Select Authorize and Capture to authorize a transaction and capture the payment in the same step. We recommend you use this option if you sell digital goods or products that are in stock and are ready to be shipped immediately after purchase. |
| Title | By default, this field displays BlueSnap Google Pay. This label is displayed to the shopper post-purchase. |
| Allow Pre-paid Cards | Select Yes if you want to allow your customers to use pre-paid cards. Select No if you do not want to present this option. |
| Card Types | Select the card types that should be visible to shoppers during checkout. Visa and MasterCard are enabled by default. |
- If the installation was successful, you will also see the BlueSnap Sofort section. Click this section to expand it. Configure the following settings.
| Setting | Description |
|---|---|
| Enable this Solution | _ If you want to offer Sofort as a payment method for your shoppers, contact BlueSnap Merchant Support and ask for Sofort to be enabled for your account. Once it is enabled, you will be able to select Yes to allow shoppers to pay with Sofort. _ Select No if you do not want to present this option. |
| Title | By default, this field displays BlueSnap Sofort. This label is displayed to the shopper post-purchase. |
| Sort Order | Enter an integer to change the position of the BlueSnap Sofort payment method in the list of other payment methods. The payment method with the smallest Sort Order appears at the top of the checkout form. |
- If the installation was successful, you will also see the BlueSnap Subscriptions section. Click this section to expand it. Configure the following settings.
| Setting | Description |
|---|---|
| User Can Cancel | Select Yes if you want your users to be able to cancel their subscriptions. |
| User Can Change Plan | Select Yes if you want your users to be able to change their plan. |
| User Can Pause Subscription | Select Yes if you want your users to be able to pause their subscriptions. |
- If the installation was successful, you will also see the BlueSnap iDEAL section. Click this section to expand it. Configure the following settings.
| Setting | Description |
|---|---|
| Enable this Solution | _ If you want to offer iDEAL as a payment method for your shoppers, contact BlueSnap Merchant Support and ask for iDEAL to be enabled for your account. Once it is enabled, you will be able to select Yes to allow shoppers to pay with iDEAL. _ Select No if you do not want to present this option. |
| Title | By default, this field displays BlueSnap iDEAL. This label is displayed to the shopper post-purchase. |
| Sort Order | Enter an integer to change the position of the BlueSnap iDEAL payment method in the list of other payment methods. The payment method with the smallest Sort Order appears at the top of the checkout form. |
- Click Save Config.
- If you have Magento caching enabled, log in to your Magento store as an admin, go to System > Cache Management, and click Flush Magento Cache.
Step 4: Enable SSL
BlueSnap requires a secure connection to process payments. Complete the following steps:
-
Install SSL on your server.
-
Log in to your Magento store as an admin and go to Stores > Configuration > General > Web.
-
In the Base URLs (Secure) section, configure the following:
- Ensure that the Secure Base URL starts with:
https:// - For Use secure URLs on Storefront and Use secure URLs in Admin, clear the Use system value checkbox, and set each to Yes.
- Click Save Config.
Step 5: Currency configuration
-
Log in to your Magento store as an admin and go to Stores > Configuration > General > Currency Setup.
-
Set the following:
- Base Currency
- Default Display Currency
- Allowed Currencies — Only choose currencies supported by BlueSnap.
-
Click Save Config.
-
If you have Magento caching enabled, go to System > Cache Management, and click Flush Magento Cache.
-
Go to Stores > Currency Rates.
-
In the Import Service box, select BlueSnap. This lets you import the BlueSnap currency rates.
-
Click Import.
The table shows the currency conversion rates. -
Click Save Currency Rates.
-
If you have Magento caching enabled, go to System > Cache Management, and click Flush Magento Cache.
Step 6: IPN Setup
Instant Payment Notifications (IPNs) are webhooks that trigger an HTTP POST message to your Magento account when an important event occurs. Follow the steps below to set up IPNs.
-
Log in to your BlueSnap account and go to Settings > IPN Settings.
-
Select the Receive Instant Payment Notifications check box.
-
Update the IPN URL(s) field. The format of the URL should follow this pattern:
https://www.yourdomain.com/bluesnap/ipn/index -
To enable specific IPNs, click Select IPNs. In the section that opens, toggle the button next to the IPN to select it. We recommend enabling the following IPN types:
- AUTH_ONLY
- AUTH_ONLY_SINGLE_CHARGE
- CANCEL_ON_RENEWAL
- CANCELLATION
- CANCELLATION_REFUND
- CHARGE
- CHARGEBACK
- CHARGEBACK_STATUS_CHANGED
- CONTRACT_CHANGE
- DECLINE
- FAILED_PAYOUT_TRANSFER
- RECURRING
- REFUND
- SUBSCRIPTION_CHARGE_FAILURE
- SUBSCRIPTION_REMINDER
-
Click Submit.
For more information on IPNs, refer to our IPN documentation.
Capture Payments
To capture a payment that has been authorized, follow the steps below.
Note: Manually capturing transactions is relevant when the Payment Action is set to Authorize Only in the BlueSnap Configuration.
-
In your Magento store admin account, go to Sales > Orders.
-
Click View next to the relevant order.
-
On the top menu bar, click Invoice and scroll to the bottom of the page where you see a drop-down list; choose Capture Online from this list.
-
Click Submit Invoice.
Kount Fraud
We offer world-class online payment fraud prevention with Kount. It's available in three tiers:
- Portfolio: Standard (active for all accounts)
- Custom: Advanced Customization
- Complete: Fully customizable and supports User Defined Fields (UDFs)
You can learn more about each fraud level here.
To enable Bluesnap Kount UDF Fraud Rule checks, follow the steps below.
- To use User Defined Fields (UDFs), you need to upgrade to Kount Complete. Contact BlueSnap Merchant Support to enable Kount Complete on your account.
- If you have contacted BlueSnap to have Kount Complete activated and you would like to add User Defined Fields (UDFs) to your fraud screening, you can do this within Kount.
While each environment is slightly different, below is an example of how you might include UDFs. We expect you will build your integration/website to set an array of key values for the customer session:
Magento\Customer\Model\Session
Example:$session->setKountUserDefinedData(['MerchantsFirstKey' => 'Merchants First Keys Value'']);
LatAm Local Card Processing
Contact BlueSnap to have LatAm Local Card Processing enabled.
Local credit card processing is available for the following card brands:
- Argentina: Amex, Argencard, Cabal, Cencosud, Diners, MasterCard, Nativa, Tarjeta Naranja, Tarjeta Shopping, Visa
- Brazil: Amex, Cartão MercadoLivr, Discover, ELO, Hipercard, JCB, MasterCard, Visa
- Chile: Amex, Diners, MasterCard, Visa
- Colombia: Amex, Diners, MasterCard, Visa
- Mexico: Amex, MasterCard, Visa
Auth Only Requests
Auth Only requests are supported for Brazil and Mexico. An Auth Only attempt for Argentina, Chile, or Colombia will fail.
Updated 4 months ago