- 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.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 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 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 in that Asaas account first. A Pix key identifies the account that receives the transfer.
- Permission to create connections in your Lovable workspace.
Asaas charges payment processing fees 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 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.
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. 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.
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 and select Asaas. For the other places to open the catalog from, see 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:
- Environment: choose Production for real payments or Sandbox for testing.
- 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 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.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 and confirm the payment. A banking app cannot pay a sandbox QR code.Switch from sandbox to production
To accept real payments, create a separate Asaas connection 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 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 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.
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.
- 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: 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 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 for the steps and who can delete.