Initial settings

After installing the module, configure the environment, the API Key, the Webhooks, and the payment methods that will be displayed at checkout.

When you are done, validate a complete purchase and confirm that the order is updated automatically after payment.

Before you begin

Confirm that:

• the Asaas module is installed;
• the Asaas account is active;
• you have an API Key for the environment that will be used;
• you have administrative access to Magento.

If you have not installed the module yet, see Installing the module.

How it works

%%{init: {"flowchart": {"nodeSpacing": 18,"rankSpacing": 24,"diagramPadding": 4,"padding": 7}}}%%
flowchart TD
    A["Configure the module"] --> B["Customer places the order"]
    B --> C["Create charge in Asaas"]
    C --> D["Customer makes the payment"]
    D --> E["Asaas sends the Webhook"]
    E --> F["Magento updates the order"]

    classDef inicio fill:#DBEAFE,stroke:#2563EB,color:#1E3A8A,stroke-width:3px
    classDef validacao fill:#E0F2FE,stroke:#0284C7,color:#0C4A6E,stroke-width:2px
    classDef sucesso fill:#DCFCE7,stroke:#16A34A,color:#14532D,stroke-width:3px

    class A inicio
    class B,C,D,E validacao
    class F sucesso

    linkStyle default stroke:#94A3B8,stroke-width:2px

1. Configure the customer address

In the Magento admin panel, go to:

Stores > Configuration > Customers > Customer Configuration > Name and Address Options

In Number of Lines in a Street Address, enter 4.

2. Open the Asaas settings

Go to:

Stores > Configuration > Sales > Payment Methods

Expand Asaas pagamentos.

Enable the module

In the option responsible for activating the module, select Yes.

3. Configure the integration

API Key

Enter the API Key corresponding to the selected environment.

Production and Sandbox keys are different. If you need to create a new key, go to the Asaas web interface under Integrations > API Keys.

See how to create and manage API keys.

Environment

Select the environment used by the module:

• Desenvolvimento (Development);
• Produção (Production).

The API Key entered must belong to the corresponding environment.

URL for payment Webhooks

The module displays a URL for receiving charge updates.

Use this URL when configuring the payment Webhook in your Asaas account. It is through this Webhook that financial changes are sent to Magento so that orders are updated automatically.

See how to create a Webhook through the web application.

Prefer this Webhook-based synchronization over periodic API queries.

Display order

Define the order in which the payment methods enabled by the module will be displayed at checkout.

Enable notifications between Asaas and the buyer

Define whether the buyer will receive emails related to payment status changes.

4. Configure credit card

Enabled

Enable or disable credit card payments.

Installments

Define:

• the maximum number of installments;
• the interest percentage applied according to the number of installments.

Credit Card Type

Select the card brands that will be displayed on the credit card form.

5. Configure bank slip (boleto)

Enabled

Enable or disable bank slip (boleto) payments.

Bank slip validity days

Enter how many days will be added to the current date to set the charge due date.

Instructions to the user

Define the message displayed on the thank-you page after the order is completed.

6. Configure Pix

Enabled

Enable or disable Pix payments.

Pix validity days

Enter how many days will be added to the current date to set the validity of the Pix payment.

Instructions to the user

Define the message displayed on the thank-you page after the order is completed.

7. Validate the integration

Before using the configuration in Production:

1. select the correct environment;
2. confirm that the API Key belongs to that environment;
3. make a test purchase;
4. check that the charge was created in the Asaas account;
5. complete or simulate the payment change;
6. confirm that the Webhook automatically updated the order in Magento;
7. validate the installment, due date, and instruction settings displayed at checkout.

Expected result

The checkout should display only the enabled payment methods and use the rules configured for each method.

After a financial change in Asaas, the corresponding order should be updated automatically in Magento through the Webhook.

Common errors

Invalid API Key

Check that:

• the key was copied in full;
• the key is still active;
• the credential corresponds to the selected environment.

Order is not updated automatically

Check the Webhook configuration.

If the payment is updated in Asaas but the order remains unchanged in Magento, confirm that the module URL was registered correctly in the payment Webhook.

See the Magento FAQ.

Expired Pix or overdue bank slip

Review the validity days configured for the respective payment method.

Card does not show the expected installments

Review the maximum number of installments and the interest configured in the module.

Next steps

• See the Magento FAQ
• Configure and manage Webhooks through the web application
• Manage your API keys
• Go back to the Magento integration overview