DiscordStatus
Guias / Guides

Installing the module

How to use Asaas in Magento

Magento/Asaas Integration Module

The official Asaas module for Magento allows you to integrate your store with Asaas to process payments via Pix, bank slips and credit cards.

After installation and configuration, orders created in Magento will use the configured Asaas account to process payments.

When to use the Asaas module

The official Asaas module for Magento is recommended for stores that want to use Asaas as their payment gateway without the need to develop a custom integration.

The installation is recommended for operations that want to:

  • receive payments via Pix, bank slips and credit cards;
  • offer credit card installments;
  • centralize financial processing in the Asaas account;
  • use an official integration compatible with Magento;
  • automate order updates through communication between Magento and Asaas.

The module can be used both in new stores and in existing operations that want to replace or add a new payment method.

What the module does

After installation and configuration, the module allows you to:

  • process payments through Asaas;
  • offer Pix, bank slips and credit cards at checkout;
  • automatically update orders according to financial events;
  • offer credit card installments;
  • send payment notifications to buyers, when enabled;
  • synchronize information between Magento and Asaas.

Requirements

Before starting the installation, it is necessary that:

  • there is an active Asaas account;
  • the account API Key is available;
  • the store uses Magento 2.3.x or 2.4.x;
  • the environment has PHP 7.1.x or higher;
  • modules can be installed through Composer or the application directory;
  • the environment has the appropriate permissions to execute Magento commands.
📘

Important

It is recommended to perform the installation first in a staging environment and only then replicate the changes to production.

Important behaviors

After installation, the module still needs to be configured in the Magento administrative panel.

The settings configured afterward will define:

  • operating environment (production or development);
  • integration credentials;
  • enabled payment methods;
  • credit card installments;
  • bank slip expiration period;
  • Pix expiration period;
  • webhooks responsible for updating orders.

Without these settings, the module will not be able to process payments.

Operational impacts

Installing the module changes the store's financial flow and makes it dependent on communication between Magento and Asaas.

For this reason, it is recommended to:

  • keep backups up to date;
  • test the complete flow before publishing to production;
  • validate order creation and payment confirmation;
  • review settings after Magento updates;
  • monitor payment behavior during the first sales.

Post-installation validation example

After completing the installation, it is recommended to validate the following flow:

Install module
↓
Configure API Key
↓
Enable payment methods
↓
Perform a test purchase
↓
Confirm payment
↓
Validate automatic order update

Installation

We recommend that you have a testing environment to validate changes and updates before updating your production store. We also recommend creating a backup of all information before performing any update or installation procedure.

Compatible versions:

  • 2.3.x
  • 2.4.x

Requirements:

  • PHP version 7.1.x or higher is required.

📘

Through Adobe Marketplace

You can obtain the module (completely free of charge) through Adobe's official application store.

To do so, access the following link:

https://commercemarketplace.adobe.com/asaas-module-magento2.html

Once the module has been added to the cart and the purchase has been completed, you can proceed with the installation by following the instructions provided by Adobe.

For detailed information, visit:

https://experienceleague.adobe.com/pt-br/docs/commerce-operations/installation-guide/tutorials/extensions


📘

Through the Asaas repository ($git clone)

  • Download the module by cloning the repository and follow the steps below according to how your store was installed:

Install using Composer

  1. Install through Packagist

  • composer require asaas/module-magento2

  • At this stage, Magento authentication credentials may be requested. If you have any questions, there are instructions available in the official documentation.

  1. Run the following commands:
  • php bin/magento setup:upgrade
  • php bin/magento setup:static-content:deploy

or

  • php bin/magento setup:static-content:deploy pt_BR

according to your store settings.

📘

Install using GitHub

If your store was created by cloning or downloading the Magento project, follow these steps:

  1. Extract the contents of the ZIP downloaded from the official repository and move the directory to:

app/code/Asaas/Magento2

  1. Verify that the directories are correctly organized.

  2. Run:

bin/magento setup:upgrade

  1. Run:

bin/magento setup:di:compile

  1. Run:

bin/magento setup:static-content:deploy -f

  1. Run:

bin/magento cache:clean

Common errors

Invalid API Key

This may occur when the configured credential belongs to another account or was copied incorrectly.

Module does not appear in Magento

This may indicate an installation failure or the need to run the update and cache cleaning commands again.

Order is not updated automatically

This may occur due to the absence or incorrect configuration of the webhook.

Problems after updating Magento

It is recommended to validate module compatibility and perform tests before applying updates in production.

Next steps

After completing the module installation, it is recommended to continue with:

  • Magento initial settings;
  • Asaas API Key configuration;
  • Magento + Asaas integration FAQ.