How to connect my Asaas payment gateway
Connect your Asaas account to Baila (the BYOG model) so you receive payments directly, with nobody in between.
Baila uses the BYOG (Bring Your Own Gateway) model: the ticket money lands straight in your Asaas (the payment gateway) account, without ever passing through Baila. For that to work, you have to connect your Asaas account to the dashboard once.
Before you start
You will need:
- An active Asaas account with a verified CPF (Brazilian taxpayer ID) or CNPJ (Brazilian company tax ID)
- Your Asaas API key (production or sandbox) — get it at asaas.com under
Perfil(top-right corner) →Integrações→Chaves da API - Your Baila profile already filled in with a CPF/CNPJ (see the related article)
Step by step
In the Baila dashboard, open Settings in the side menu (the gear icon) and go to the Payment Gateway Settings screen.
Paste the API key you copied from the Asaas dashboard and click Save settings.
Once saved, click Validate credentials. Baila makes a test call to the Asaas API to confirm the key works. If it fails, review the status of your Asaas account (verified CPF/CNPJ, account active and with nothing outstanding) before trying again. Until the gateway is validated, you cannot publish paid events.
Next, set up the webhook in the Asaas dashboard following the section below. Without it, payment confirmations, refunds, and chargebacks never reach Baila.
Never share your Asaas API key. It grants full access to the account your money lands in. If you suspect it leaked, revoke the key in the Asaas dashboard immediately and generate a new one.
Setting up the webhook at Asaas
In the Asaas dashboard, go to Integrações → Webhooks → Adicionar Webhook and fill in exactly the fields below. Without this step, Baila receives no payment confirmations, refunds, or chargebacks. The Asaas dashboard is Portuguese-only, so each field is given below by its literal Asaas label with the English meaning next to it.
Webhook details
-
Este Webhook ficará ativo?(will this webhook be active?) — turn the toggle on. -
Nome do Webhook(webhook name) — any name you recognize, for exampleBaila. -
URL do Webhook(webhook URL) — paste exactly:https://api.vaidebaila.app/api/webhooks/asaas -
E-mail— an address you actually check: Asaas uses it to warn you if webhook delivery fails. -
Versão da API(API version) — selectv3. -
Token de autenticação(authentication token) — paste the webhook token generated by Baila. In the Baila dashboard, on the Payment Gateway Settings screen, under Webhook Settings, click Generate token — the value (in thebaila_whk_...format) is copied to your clipboard automatically. That token is how Baila confirms the webhook really came from your Asaas account. -
Tipo de envio(delivery mode) — selectSequencial(sequential; recommended, so event order is preserved). -
Fila de sincronização ativada?(sync queue enabled?) — leave it on.
Events to tick
Under Adicionar Eventos → Cobranças (charges), tick the events below.
Shortcut: you can click Selecionar Todos (select all) in the Cobranças section — the extra events are ignored by Baila with no side effects.
If you would rather tick only what is needed, enable just these (Baila ignores the rest):
PAYMENT_RECEIVEDPAYMENT_CONFIRMEDPAYMENT_OVERDUEPAYMENT_DELETEDPAYMENT_REPROVED_BY_RISK_ANALYSISPAYMENT_REFUND_IN_PROGRESSPAYMENT_REFUNDEDPAYMENT_CHARGEBACK_REQUESTEDPAYMENT_AWAITING_CHARGEBACK_REVERSALPAYMENT_CHARGEBACK_DISPUTE
Click Salvar (save) in the top-right corner to finish.
What happens if the key expires
If Asaas revokes or invalidates your key, Baila can no longer capture payments. You will not be able to publish new paid events until you register the key again and validate it under Payment Gateway Settings.