> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lovable.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect your app to Asaas

> Connect your app to Asaas to accept Pix, boleto, and credit card payments in Brazil, track which orders are paid, and manage recurring charges.

[Asaas](https://www.asaas.com/) processes payments for businesses in Brazil. Connect your Lovable app to your Asaas account to charge customers in Brazilian reais and match each payment to an order or subscription.

Asaas is available as an [app + chat connector](https://docs.lovable.dev/integrations/app-connectors.md): one shared connection that works in [Chats](https://docs.lovable.dev/features/chats.md), in the project chat while you build, and in your published apps.

With Asaas, your app can:

* Show a Pix QR code or a copy-and-paste code for a buyer to pay by instant bank transfer.
* Send buyers to an Asaas payment page to pay by credit card or boleto (a Brazilian bank slip).
* Create subscriptions, split a purchase into installments, or refund a payment.
* Check payment status before fulfilling an order or granting access to a membership.

## Common use cases and example apps

Choose a prompt that matches how your customers pay.

| Example app | Example prompt | Description |
| :- | :- | :- |
| Event registration | *Use Asaas and build a registration page where attendees pay by Pix.* | **Issue tickets after payment.** The app shows a Pix QR code and releases the ticket when Asaas confirms payment. |
| Service invoices | *Use Asaas and build a client portal where customers can pay an outstanding charge by boleto or card.* | **Give each client a payment page.** The app links to the Asaas page so the client enters card details there, not in your app. |
| Membership billing | *Use Asaas and build a monthly membership with recurring card payments.* | **Renew access after each paid cycle.** The app tracks the subscription and extends membership when Asaas confirms the charge. |
| Tuition installments | *Use Asaas and build a payment plan that splits one course fee into four boleto installments.* | **Show what students still owe.** The app lists each installment, its due date, and whether the student has paid it. |
| Collections dashboard | *Use Asaas and build a dashboard showing which orders are paid, overdue, or refunded.* | **Find orders that need attention.** The app matches Asaas charges to order references so staff can follow up on the right order. |

## How to connect Asaas

Who can create Asaas connections depends on your plan and workspace settings. App + chat connectors are available by default. On Business and Enterprise plans, [Who can create connections and clients](https://docs.lovable.dev/integrations/admin-controls.md#who-can-create-connections-and-clients) starts at **Admins**. Some Enterprise workspaces start at **No one**, which disables the connector. An admin or owner changes it in **Connectors → Admin settings → App + chat connectors**.

You can create separate Asaas connections for sandbox and production. When the connection is created, you can [link it to the projects](https://docs.lovable.dev/integrations/app-connectors.md#link-a-connection-to-a-project) where you want to use it. Anyone building in a project can ask Lovable in the project chat to link their project to it. Linking follows the connection's access rules.

### Prerequisites

Before connecting Asaas, make sure you have:

* Admin access to the Asaas account for the environment you want to connect.
* To show Pix QR codes in your app with this connector, [register a Pix key](https://docs.asaas.com/docs/payments-via-pix-or-dynamic-qr-code) in that Asaas account first. A Pix key identifies the account that receives the transfer.
* Permission to [create connections in your Lovable workspace](https://docs.lovable.dev/integrations/admin-controls.md#who-can-create-connections-and-clients).

> [!NOTE]
>
> Asaas charges [payment processing fees](https://www.asaas.com/precos-e-taxas) to your Asaas account, not your Lovable workspace.

### Step 1: Get an Asaas API key

Use the Asaas web dashboard to create a key. Asaas issues separate keys for sandbox and production.

**1. Choose your Asaas account**

To test without moving money, sign in to [Asaas Sandbox](https://sandbox.asaas.com/) or create a sandbox account. Asaas can send emails and text messages from the sandbox, so use your own contact details for test customers.

To accept real payments, sign in to your [Asaas production account](https://www.asaas.com/).

**2. Create a key for Lovable**

In the dashboard for the environment you chose, open **Integrations → API Keys**. For production, you can go directly to the [Asaas API keys page](https://www.asaas.com/customerApiAccessToken/index). Create a key and give it a name you recognize, such as `Lovable`.

If you restrict the key to authorized IP addresses in Asaas, the connector cannot use it. Use a key without that restriction for Lovable.

**3. Copy and store the key**

Asaas shows the key only once. Save it securely before leaving the page. Paste it into the Lovable connection form, not the project chat.

See the [Asaas API keys guide](https://docs.asaas.com/docs/api-keys) for instructions on managing or replacing a key.

### Step 2: Connect Asaas to Lovable

Use the API key from the account you chose in Step 1.

**1. Open Asaas in Connectors**

Open [Connectors](https://lovable.dev/dashboard?connectors) and select **Asaas**. For the other places to open the catalog from, see [Where to find connectors](https://docs.lovable.dev/integrations/introduction#where-to-find-connectors).

**2. Add a connection**

Click **Connect** on the connector page. The form has three sections: **Details**, **Configure connection**, and **Sharing**.

**3. Name the connection**

Under **Details**, replace the suggested name with one that identifies the environment, such as `Asaas sandbox` or `Asaas production`.

**4. Configure the connection**

Under **Configure connection**, enter:

1. **Environment**: choose **Production** for real payments or **Sandbox** for testing.
2. **API key**: paste the complete key from the matching Asaas account, including the initial `$`.

**5. Choose who can use this connection**

Under **Sharing**, the connection is private to you by default and shows a **Private** label. To share it, click **Share with others**. Then add workspace members by email, or click **Invite entire workspace** to make the connection available to everyone in your Lovable workspace.

Anyone you share a production connection with can use it to create real charges and issue refunds.

See [Who can use connections and clients](https://docs.lovable.dev/integrations/admin-controls.md#who-can-use-connections-and-clients) for more information.

**6. Connect**

Click **Connect** at the bottom of the form. Lovable checks the key by reading the customer list without creating a customer or a charge.

If the key belongs to the other Asaas environment, Lovable shows an error instead of creating the connection. Choose the matching **Environment** or paste a key for the environment you selected.

If Asaas reports too many requests (`429`) or an error on its servers (`5xx`), Lovable creates the connection without verifying the key.

When connected, anyone building in a project can ask Lovable in the project chat to link their project to Asaas. Linking follows the connection's access rules.

### Test a Pix payment in the sandbox

Before testing, ask Lovable in the project chat to check which Asaas environment your app uses. Continue only if it uses **Sandbox**. Charges in **Production** are real.

Start a Pix payment in your app to create a test charge. Open that charge in the [Asaas Sandbox dashboard](https://sandbox.asaas.com/) and [confirm the payment](https://docs.asaas.com/docs/adding-balance-to-a-sandbox-account). A banking app cannot pay a sandbox QR code.

### Switch from sandbox to production

To accept real payments, [create a separate Asaas connection](#step-2-connect-asaas-to-lovable) with **Production** selected and a key from your production account. Your sandbox customers and charges stay in the sandbox.

[Unlink this project from the sandbox connection](https://docs.lovable.dev/integrations/app-connectors.md#unlink-projects-from-a-connection) before linking the production connection. In the project chat, ask Lovable to link your production Asaas connection and select it by name when prompted.

A webhook is a message Asaas sends your app when a payment changes. Lovable registers a separate webhook in each Asaas account.

If you’re not sure which stack your app uses, ask Lovable in the project chat: “Does this app use TanStack Start or React + Vite?”

* **TanStack Start:** [Publish the app](https://docs.lovable.dev/features/publish.md) so Asaas can reach the webhook at the published address.
* **React + Vite:** The app receives payment updates through a backend function. You don’t need to publish the app to register the webhook.

Ask Lovable in the project chat to register the webhook in your production Asaas account.

## Limitations

Keep these differences in mind when choosing how to bill customers:

* A standard Pix or boleto subscription issues a new charge each cycle. The buyer still needs to pay each charge. For automatic card billing after the first payment, use a [credit card subscription](https://docs.asaas.com/docs/subscription).
* Each connection represents your Asaas account. Customers can pay you through your app, but they cannot sign in with their own Asaas accounts through the connector.

## Manage your Asaas connection

Connections are managed from [**Connectors**](https://lovable.dev/dashboard?connectors): select **Asaas**, then open the connection.

* **Unlink projects** to remove Asaas access from specific projects while keeping the connection available for others. See [Unlink projects from a connection](https://docs.lovable.dev/integrations/app-connectors.md#unlink-projects-from-a-connection) for the steps.
* **Delete the connection** to remove it from the workspace entirely. Deleting is permanent. It removes the credentials from all linked projects, and app features that use Asaas stop working until a new connection is added. See [Delete a connection](https://docs.lovable.dev/integrations/app-connectors.md#delete-a-connection) for the steps and who can delete.
