Initial settings

First steps when using Asaas in WooCommerce.

After installing the Asaas Plugin for WooCommerce, connect your store to your Asaas account using an API Key.

First configure the environment and the credential. Then, enable the payment methods that will be used at checkout.

Before you start

Confirm that:

the Asaas Plugin is installed and active;
you have an account in the environment that will be used;
an administrator user of the Asaas account can create the API Key.

For the first tests, use the Sandbox. Move to Production after validating the checkout and order updates.

See the Sandbox guide.

1. Choose the environment

The plugin can operate in Sandbox or Production.

📘
Important
The Sandbox and Production environments are completely independent.
Each environment has its own customers, charges, settings, and API Keys. An API Key created in the Sandbox will not work in Production and vice versa.

Define the environment before generating or configuring the key.

2. Generate the API Key

In the Asaas account of the chosen environment, go to:

User menu → Integrations → Generate new API Key

Copy the entire generated key.

The key is displayed only once. Store it before leaving the screen.

See how to create and manage API keys.

3. Configure the API Key in WooCommerce

Open one of the payment methods provided by the Asaas Plugin and locate the API section.

Configure:

Environment: select Sandbox or Production;
API Key: enter the full key created in the same environment.

The plugin will validate the credential automatically.

If successful, the following message will be displayed:

✅
Valid API key

If validation fails, confirm:

that the selected environment matches the API Key's environment;
that the API Key was copied in full;
that the key is still active in the Asaas account.

After validation, save the changes.

⚠️
Attention
Using an API Key that does not match the selected environment will prevent the integration from creating charges.
We recommend running all tests in the Sandbox environment before configuring your store in Production.

❗️
Protect your API Key
The API Key has access to your Asaas account and allows financial operations to be performed.

Never share your API Key in support conversations.

Do not publish the key in public repositories.

Store it only in secure environments.

4. Enable the payment methods

Go to:

WooCommerce > Settings > Payments

The payment methods provided by the Asaas Plugin will be displayed on this screen.

Enable only the payment methods the store will use.

The specific settings for Pix, bank slip, and credit card are covered in Payment methods.

API Key and Webhook are shared

📘
API Key and Webhook
The API Key and Webhook settings appear in every Asaas Plugin payment method, but they are shared among all of them.
This means you only need to configure them once.
To understand how automatic order synchronization and the webhook configuration work, see the Webhooks page.

Starting with Asaas Plugin version 2.5, a valid API Key also triggers the automatic creation and configuration of the integration's Webhook.

Use Webhooks to track charge changes and update orders, without periodic queries.

See the WooCommerce Webhooks.

Expected result

When you complete this step:

the API Key should be displayed as valid;
the store should be connected to the chosen environment;
the Asaas payment methods should be available for configuration;
the Webhook should be configured automatically by the plugin.

Next steps

Updated 2 days ago

Did this page help you?