## 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

- **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.
- **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_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.

## See also

- [Payments overview](/hc/ajuda/articles/payments-overview-en)
- [Create a charge and send it in the conversation](/hc/ajuda/articles/payments-criar-cobranca-enviar-na-conversa-en)
- [Refunds, webhooks and reports](/hc/ajuda/articles/payments-reembolsos-webhooks-relatorios-en)