Connect a gateway: Asaas and Mercado Pago

Overview

Before you can charge anyone, you need to connect a payment gateway. ConversaLabs 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

1. Open the Payments settings and choose to add a new connection.
2. Pick the gateway: Asaas or Mercado Pago.
3. Enter the credentials:
   • Asaas: paste the API Key.
   • Mercado Pago: paste the Access Token (and the signing secret used to validate the webhook).
4. Choose the environment: production or sandbox.
5. Save. The platform validates the credentials against the gateway.
6. 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.
7. Run a sandbox test (a PIX charge, for example) and confirm the status changes on its own when the payment is simulated.

Settings & options

Charge plans and payment books

Enable Payments, connect a compatible gateway and check the payer details. Available options depend on the connection, method and cycle. Asaas offers native monthly boleto/Pix installments; other cycles use capped recurrence where supported. This release adds no direct integrations with new banks.

• 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.

• Ingestion guards: these are connection settings, not import settings, and they also govern what arrives through webhooks.

  • Cutoff date: nothing older than it gets in. It is the brake that stops an entire history from showing up as if it happened today.
  • Automatic orphan-charge adoption: off by default. A charge arriving from the gateway with no local match is adopted only if you allow it; with "only from the cutoff date", a missing or invalid date makes the operation fail safely instead of guessing.
  • Both live in Import history → Ingestion settings and are saved on the connection, so the next import and the next webhook already respect them.

• Methods supported per gateway:

  Capability	Asaas	Mercado Pago
  PIX	Yes	Yes
  Boleto	Yes	Yes
  Card (hosted checkout)	Yes	Yes
  Card installments	Yes	Yes
  Subscriptions	Yes	Yes
  Reusable plans	—	Yes
  Partial refund	Yes	Yes

Connection certificate

When a connection requires a certificate, use its certificate area to upload the file and requested details. After saving, check subject, issuer, fingerprint and expiry. Editing shows metadata; it does not return the key, certificate or password. States are missing, valid, expiring and expired. Renew before expiry and recheck the metadata; expiry notifications help plan this maintenance.

The foundation allows testing this interface in a laboratory with a fictitious certificate. It neither enables a new bank nor turns a test certificate into a production credential.

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_token header (not Authorization: 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.

See also

• Payments overview

• Create a charge and send it in the conversation

• Refunds, webhooks and reports

• Charge plans and payment books

• Public payment page