Payments: Stripe, Mercado Pago, Pagar.me and Hotmart

Without a connected gateway, the app's checkout screen exists but the purchase does not complete. The money goes straight to your account at the provider: the platform does not act as an intermediary for the payment and charges no integration credits for it.

Before you start

• Plan: Builder;
• An account with the provider: Stripe, Mercado Pago or Pagar.me (creating an account and using test mode is free on all three; the per-sale fees are each provider's own);
• One gateway per app. Stripe, Mercado Pago and Pagar.me share the same slot: saving one replaces the other. Hotmart is separate and can coexist with them;
• Not for inside the store apps. In the app installed from the App Store or Google Play, the store does the charging. That is another topic, in Selling subscriptions inside the app.

They all live in the Integrations tab, Payments category.

Test before you sell

None of the three gateways has an environment switch on the card: the environment is the one of the key you paste. Always start with the test keys, make a test purchase and only then swap in the production keys.

When swapping, type the production keys into their fields. A field left blank keeps its saved value, so a test key in a field you did not type stays in effect.

When switching gateway (for example, from Stripe to Mercado Pago), the previous gateway's keys do not carry over to the new one: fill in the fields on the new gateway's card.

Stripe

Card fields: Publishable key (pk_), Secret key (sk_) and Webhook signing secret (whsec_).

1. at dashboard.stripe.com, turn on test mode;
2. under Developers → API keys, copy the publishable key (pk_test_…) and the secret key (sk_test_…);
3. on the Stripe card, paste both and leave the Webhook signing secret blank;
4. click Save and activate.

The platform tests the secret key and creates the webhook on its own in your Stripe account. The card shows the Webhook URL block with the Automatic badge and the list of events: there is nothing to do in the Stripe dashboard.

For production, repeat with test mode off (pk_live_… and sk_live_…).

Mercado Pago

Card fields: Public Key, Access Token and Webhook secret key.

Mercado Pago does not allow creating the webhook through the API, so this is the only one of the three with a manual step.

1. at mercadopago.com.br/developers/panel, create an application;
2. under Test credentials, copy the Public Key and the Access Token;
3. on the Mercado Pago card, paste both and click Save and activate;
4. the card now shows the Webhook URL block with the Manual badge, the URL with a Copy button and the Events to enable;
5. in the Mercado Pago dashboard, under Your integrations → Webhooks, paste the URL, tick the listed events and save;
6. copy the secret key Mercado Pago generated for that webhook;
7. go back to the card, fill in Webhook secret key and click Save and activate again. Public Key and Access Token can stay blank: the saved value is kept.

Without the webhook secret key, the platform cannot confirm the payment notifications, and the purchase unlocks nothing in the app.

Pagar.me

Card fields: API key (secret) and Public key (encryption).

1. in the Pagar.me dashboard, go to Settings → API keys and choose the test environment;
2. copy the secret key (sk_…) and the public key (pk_…);
3. on the Pagar.me card, paste both and click Save and activate;
4. the card shows the Webhook URL block with the Manual badge. The URL already includes a username and a password generated by the platform: treat it as a secret;
5. in the Pagar.me dashboard, under Settings → Webhooks, paste that URL and tick the Events to enable the card lists.

There is no webhook secret field to fill in for Pagar.me: the authentication already travels inside the URL.

Hotmart

Hotmart is not an app gateway. It sells through its own website, and the integration makes the app recognize who has already bought and unlock access on its own.

Card fields: Client ID, Client Secret, Hottok (from the Webhook), Product code(s) that unlock the app and the option Use the test environment (sandbox).

1. in Hotmart, under Tools > Developer Credentials, create the credential and copy the Client ID and the Client Secret;
2. under Tools > Webhook, copy the hottok;
3. on the Hotmart card, fill in the fields. In Product code(s) that unlock the app, enter the product code (separate with commas if there is more than one);
4. tick Use the test environment (sandbox) only if the credentials are test ones;
5. click Save and activate. The platform asks Hotmart whose account it is and shows "Connected to Hotmart (name)." with the account name in parentheses, which confirms you connected the right account;
6. copy the Webhook URL the card shows and paste it into the Hotmart dashboard, under Tools > Webhook, choosing the purchase and subscription events.

Inside the app published on the stores, the sale cannot happen: the app only unlocks what was bought on the website.

How to make the first test payment

1. connect the gateway with the test keys;
2. if the app does not have a purchase screen yet, ask for one in the chat (for example: "create the plans page with a subscribe button"). That part costs AI credits, like any building;
3. open the app and make a purchase. On Stripe, the test card is 4242 4242 4242 4242, with any future date and any security code. On Mercado Pago and Pagar.me, use the test cards from each one's documentation;
4. check the purchase in the provider's dashboard, in test mode, and see whether the app unlocked what was bought.

Only swap to the production keys after that whole cycle has worked.

How to know it worked

• the card shows Connected. On the three gateways and on Hotmart, that badge comes from a real test with the provider, not just from the saved form;
• on Stripe, the webhook block has the Automatic badge;
• on Mercado Pago, the webhook secret key was saved after creating the webhook in the dashboard;
• the test purchase shows up in the provider's dashboard and the app unlocks access.

Common problems

• Configuration error right on save. The secret key was refused: check that you copied the secret key (and not the publishable one) and that no space was left at the start or the end;
• The payment is approved at the provider and the app unlocks nothing. It is the webhook. On Mercado Pago, the secret key or an event is missing. On Pagar.me, the pasted URL is not the one the card shows, or an event is missing;
• I switched gateways and the old one stopped. That is expected: only one is active per app;
• The subscribe button does not show up in the app installed from the store. Inside the store apps the gateway is never used. See Selling subscriptions inside the app.