N8N

You will understand when to use the official Asaas node in n8n and how to structure financial workflows safely through to production execution.

What is n8n?

n8n is an open-source workflow automation platform that allows you to integrate applications, APIs, databases, and services through a visual interface, reducing the need to develop custom integrations.

Through nodes, you create automated flows capable of executing actions between different systems, processing information, reacting to events, and orchestrating business processes.

Asaas provides an official node for n8n that allows you to use Asaas API features directly in platform workflows, without implementing HTTP calls manually.

When to Use It

Use the official Asaas node for n8n when you need to automate financial processes without developing a full code-based integration.

It is recommended for scenarios such as:

• automatically creating customers from forms, CRMs, or spreadsheets;
• issuing charges after an order is placed in an e-commerce store;
• automatically creating recurring subscriptions;
• integrating payments with ERPs, CRMs, and support platforms;
• executing automatic actions after receiving webhooks;
• synchronizing financial data between different systems.

Consider a direct API integration when your flow requires very specific business rules, detailed retry control, advanced concurrency handling, or logic that does not fit well into n8n's visual modeling.

Prerequisites

Before creating workflows with the Asaas node, complete these steps:

1. Create an active Asaas account in Production or Sandbox.
2. Generate a valid API Key for the environment that will be used in the workflow.
3. Install a compatible version of n8n.
4. Meet the minimum Node.js requirements for your n8n environment.
5. Install the official Asaas node following the Installation page.
6. Validate API authentication on the Authentication page.

Key Concepts

Available Resources

After installing the Asaas node, you will be able to use resources such as:

• Customers;
• Charges;
• Subscriptions;
• Installment plans;
• Pix (Cash-in);
• Notifications;
• Business data;
• Financial data;
• Webhooks.

New resources may become available as new versions of the node are published.

Essential Parameters and Settings

Configure these items before running a workflow that uses Asaas:

Implementation Flow

Follow this sequence to create an automation with the Asaas node:

1. Define the workflow objective. Example: create a charge when a new order is received.
2. Configure the n8n trigger. The trigger can come from another system, a manual execution, a schedule, or a webhook.
3. Add the Asaas node. Select the resource that represents the desired financial action.
4. Choose the operation. Configure the action to be executed within the selected resource.
5. Map the input data. Match the data received in the workflow with the fields required by the Asaas operation.
6. Run in Sandbox. Validate whether the operation creates, queries, or updates the expected data.
7. Handle success and error. Route successful responses to the next nodes and error responses to a correction or notification flow.
8. Monitor executions. Track authentication, validation, communication, and usage limit failures.
9. Publish to Production. Use Production credentials only after the flow has been validated.

Example Journey: Creating a Charge from an Order

Use this template as a reference to structure a charge automation:

Order created in the source system
↓
n8n workflow is triggered
↓
Customer data is prepared
↓
Asaas node creates or queries the customer
↓
Asaas node creates the charge
↓
Workflow saves the identifier returned by the API
↓
Workflow sends confirmation to the source system
↓
Asaas webhook reports payment updates

In this flow, the workflow does not end at charge creation. To keep the source system up to date, also configure the step for receiving Asaas events via webhooks.

See Introduction - Webhooks, Receive Asaas Events at Your Webhook Endpoint, and Events for Charges to plan payment tracking.

Important Behaviors

The Asaas node acts as a client of the official Asaas API.

This means that:

• operations follow the same rules as the REST API;
• errors returned by the API will also be returned to the workflow;
• authentication is performed through the API Key configured in the credentials;
• usage limits, business rules, and API validations continue to be applied normally;
• operations executed in Production can create customers, issue charges, register subscriptions, or query real financial data.

Always refer to the API Reference when you have questions about a specific resource.

Error Handling and Best Practices

When developing workflows using the Asaas node:

• use the Sandbox environment during development;
• test flows before running them in Production;
• store the API Key securely in n8n credentials;
• handle possible errors returned by the API using n8n exception handling nodes;
• avoid executing critical operations without prior validations;
• monitor workflow executions to identify failures quickly;
• record identifiers returned by the API to facilitate auditing and reconciliation.

Operational Impacts

Workflows created in n8n can execute operations directly on your Asaas account.

Depending on the resource used, an execution may create customers, issue charges, register subscriptions, or query financial data. Therefore, validate all flows in Sandbox before using them in Production.

It is also important to monitor workflow executions to identify authentication failures, communication issues, errors returned by the API, or duplicate executions.

Next Steps

Refer to these resources to continue the implementation:

• Installation — install the official Asaas node in n8n.
• Authentication — configure and validate your API Key.
• Sandbox — test your workflows before publishing to Production.
• Introduction - Webhooks — understand how to receive Asaas events.
• Events for Charges — track charge status changes.
• API Limits — plan execution frequency and request volume.
• API Reference — check fields, responses, and rules for each endpoint.