Overview
Before you can charge anyone, you need to connect a payment gateway. Conversa Labs supports Asaas and Mercado Pago. Each connection stores the gateway credentials, sets the environment (production or test) and registers a webhook — the channel the gateway uses to tell the platform when a charge is paid, becomes overdue or is refunded.
You can have more than one connection (for example, an Asaas production account and a Mercado Pago one for a different flow). Every charge is created on a specific connection.
Prerequisites
- Payments module enabled and administrator permission.
- An account on the chosen gateway:
- Asaas: an API Key from the Asaas panel.
- Mercado Pago: an Access Token and Client Secret from your application credentials.
- Decide the environment: production (real charges) or sandbox (testing).
Step by step
- Open the Payments settings and choose to add a new connection.
- Pick the gateway: Asaas or Mercado Pago.
- Enter the credentials:
- Asaas: paste the API Key.
- Mercado Pago: paste the Access Token (and the signing secret used to validate the webhook).
- Choose the environment: production or sandbox.
- Save. The platform validates the credentials against the gateway.
- Set up the webhook: the platform generates the notification URL and the verification secret. In many cases registration is automatic; when it isn't, copy the URL shown and register it in the gateway panel.
- Run a sandbox test (a PIX charge, for example) and confirm the status changes on its own when the payment is simulated.
Settings & options
-
Environment: production or sandbox per connection. Don't mix credentials from different environments.
-
Webhook: the URL is unique per connection and the gateway authenticates every notification:
- Asaas sends its own token in the request header, compared securely to the one the platform stored.
- Mercado Pago signs each notification; the platform validates the signature before processing.
-
Last reconciliation diagnostics: the scheduled check compares charges and subscriptions with the gateway to cover missed notifications. If a record fails, its connection card under Settings → Payments → Connections remains red with the total count and up to the first three external identifiers and reasons. Other records continue processing; raw responses, customer data, and credentials never appear in this diagnostic.
-
Methods supported per gateway:
Capability Asaas Mercado Pago PIX Yes Yes Boleto Yes Yes Card (hosted checkout) Yes Yes Installments Yes Yes Subscriptions Yes Yes Reusable plans — Yes Partial refund Yes Yes
Use cases
- An operator already using Asaas connects the key and starts charging on WhatsApp without switching systems.
- A business selling across Latin America connects Mercado Pago.
- A team that wants to test before charging for real uses the sandbox environment first.
Tips, limits & best practices
- Treat credentials as secrets: they are stored encrypted and never shown again on screen after you save them.
- Use sandbox to validate the whole flow before going live.
- Asaas auth uses an
access_tokenheader (notAuthorization: Bearer). - Mercado Pago notifies only the payment identifier; the platform queries the gateway to read the full state — this is expected.
Troubleshooting
- Invalid credentials: check that you copied the right key/token and that the environment matches the gateway's (a test token only works in sandbox).
- Status won't update: the webhook isn't arriving. Confirm the URL is registered on the gateway and the verification secret matches.
- Notification rejected (401): the webhook signature/token doesn't match — re-register the webhook.
- The last reconciliation had failures: note the identifier and reason shown on the card, verify the connection and environment, and confirm that the record still exists at the gateway. A failure remains visible and never silently changes the local record. The next scheduled check replaces the diagnostic; the alert disappears only after a run with no failures.