For AI agents: the complete documentation index is available at https://docs.clickmax.io/en/llms.txt, the full documentation bundle is available at https://docs.clickmax.io/en/llms-full.txt, and this page is available as Markdown at https://docs.clickmax.io/en/features/integrations/pagarme.md.
  • English

      • Integrate Pagar.me

      Create an inbound integration in Clickmax, paste your Pagar.me secret key (sk_…), and register the generated URL in Pagar.me's webhooks, with authentication turned on using the user and password Clickmax shows. From then on every event carrying the customer's email creates or updates a contact (tagged pagarme), charges become sales in Clickmax, and the events are available as automation triggers.

      Before you start

      • Workspace role: Owner, Admin, Editor or Collaborator. Finance, Guest and Attendant have no access to Integrations.
      • From your Pagar.me account you need the secret key, under Configurações > Chaves de API (Settings > API keys). It starts with sk_ (production) or sk_test_ (test). The public key (pk_…) does not replace the secret key.
      • The public key (pk_…), on the same screen, is optional. Without it the integration still receives webhooks, records sales and fires triggers, but the Checkout Pagar.me block can't sell.
      • The secret key is required to connect: Clickmax uses it to identify the plan of subscription invoices and the products of Pix/boleto charges and subscription refunds, to record chargebacks, and to list your plans in triggers.

      Step by step

      1. In Clickmax, open Integrations and select the Pagar.me card.
      2. In another tab, open the Pagar.me dashboard and log in.
      3. In Pagar.me, go to Configurações > Chaves de API (Settings > API keys) and click Criar chave (Create key):
        • Nome da chave (Key name): a name that identifies the use, such as Clickmax.
        • Leave the "Utilizo os módulos legados do Magento 2 ou Woocommerce (Mundipagg)" option unchecked.
        • Under Acesso da chave (Key access), choose Personalizado (Custom) and turn on only the Transacional (Transactional) scope, with Leitura e escrita (Read and write). Leave Financeiro (Financial) and Recebedores (Recipients) off: Clickmax doesn't use balance, transfers or recipients, and the key keeps the least access.
        • Confirm with your Pagar.me account password and click Criar chave.
        • Copy the secret key (sk_…) and paste it into the Secret key (sk_) field in Clickmax.
        • On the same Chaves de API (API keys) screen, also copy the public key (pk_…) and paste it into the Public key (pk_) field. It is optional and only needed to sell through the Checkout Pagar.me block on your pages. Both keys must be from the same environment: sk_test_ with pk_test_, or sk_ with pk_.
      4. Enter a Nickname for the integration and click Create integration. Clickmax checks the key with Pagar.me before saving.
      5. Clickmax shows the Webhook URL, the Webhook user (always clickmax) and the Webhook password. Keep this screen open.
      6. In Pagar.me, go to Configurações > Webhooks > Criar webhook (Settings > Webhooks > Create webhook) and paste the copied URL.
      7. Turn on Habilitar autenticação (Enable authentication). In Usuário do Webhook (Webhook user) paste clickmax and in Senha do Webhook (Webhook password) paste the password shown by Clickmax. Without authentication, Clickmax rejects every webhook.
      8. Select the events: order.created, order.paid, order.payment_failed, order.canceled, charge.pending, charge.refunded, chargeback.received, subscription.created, subscription.canceled, invoice.paid and invoice.payment_failed.
      9. Save the webhook in Pagar.me and click Complete integration in Clickmax.

      The user and password remain available later: open the integration in Integrations and copy them at the top of the screen.

      Sell right on your pages

      With the public key in the integration, you can sell by card, Pix and boleto through the Checkout Pagar.me block on editor pages and in the funnel's External Checkout step. Besides the keys, the Pagar.me account needs the payment methods turned on and the pages' domain allowed under Configurações > Conta > Domínios (Settings > Account > Domains); without the domain, card payments fail. See every requirement in How to sell through Pagar.me right on my page.

      Available triggers

      Each event carrying the customer's email creates or updates a contact tagged pagarme. Paid orders and paid invoices mark the contact as a customer. Events without the customer's email are ignored.

      Pagar.me eventClickmax triggerWhen it fires
      order.createdOrder createdA Pix or boleto order is created and awaits payment
      order.paidOrder paidThe order is paid
      order.payment_failedOrder payment failedThe order's payment is declined
      order.canceledOrder canceledAn order that was never paid is canceled
      charge.pendingPix/boleto generatedA Pix or boleto is generated and awaits payment
      charge.refundedCharge refundedA charge is refunded
      chargeback.receivedChargeback receivedPagar.me receives a chargeback for a charge
      subscription.createdSubscription createdA subscription is created
      subscription.canceledSubscription canceledA subscription is canceled
      invoice.paidSubscription invoice paidThe first charge or a renewal of the subscription is paid
      invoice.payment_failedInvoice payment failedThe charge of a subscription invoice is declined

      Details that change the behavior:

      • Order created fires only for orders that wait for payment (Pix and boleto). A card purchase goes straight to Order paid or Order payment failed.
      • Pix/boleto generated fires only for Pix and boleto. A card under review does not fire this trigger.
      • Order canceled does not fire when the order had already been paid and was then refunded. In that case Charge refunded fires instead, so the automation runs only once.
      • A one-off order refund arrives through Pagar.me's order.canceled event. If it isn't selected in the webhook, the refund is not recorded and Charge refunded does not fire.

      How sales are recorded

      • One sale per charge. An order paid with two payment methods creates two sales; each subscription renewal creates a new sale.
      • The same sale follows the charge. A generated Pix or boleto comes in as a pending sale and becomes paid once the payment is confirmed. Refunds and chargebacks update that same sale instead of creating another one.
      • An order with more than one product creates one sale with the charge's total value. In the external sales list the main product shows a +N badge for the additional items.
      • The secret key completes the sales. If it is revoked after connecting, one-off order sales are still recorded, but invoices and charges arrive without a product (the trigger's product filter stops matching) and chargebacks are ignored.

      Filter by product

      The trigger's product filter works differently for one-off orders and for subscriptions:

      • One-off orders (order.*, Pix/boleto generated, refund and chargeback of an order): the filter matches the order item's code (the SKU you send to Pagar.me).
      • Payment-link orders have no code on the item. In that case the filter matches the item's name — if you rename the item in Pagar.me, the trigger stops firing. Reopen the trigger, select the product again and save.
      • Subscriptions and invoices (subscription.*, invoice.*, and refund or chargeback of a subscription charge): the filter matches the plan. Pick the plan from the list, which Clickmax fetches straight from your Pagar.me using the secret key. Renaming the plan does not break the filter.

      The filter list shows your Pagar.me plans and the products that already arrived in earlier orders. If a product hasn't shown up in any order yet, you can add it manually by its code (or by its name, for payment links).

      If it didn't work

      • I can't create the integration: make sure you pasted the secret key (sk_…), not the public key (pk_…). If the key was revoked, generate another one under Configurações > Chaves de API in Pagar.me. See the error codes.
      • Clickmax says the keys are from different environments: the public key must be from the same environment as the secret key. Use pk_test_ with sk_test_ (test) or pk_ with sk_ (production).
      • The Checkout Pagar.me block doesn't sell: check that the public key is in the integration and that the page's domain is allowed under Configurações > Conta > Domínios in Pagar.me. See How to sell through Pagar.me right on my page.
      • No event arrives, or Pagar.me shows the webhooks as rejected: webhook authentication is off or the user/password doesn't match. In Pagar.me, edit the webhook, turn on Habilitar autenticação (Enable authentication) and paste the Webhook user (clickmax) and Webhook password shown at the top of the integration in Clickmax. This also applies to webhooks registered before authentication was required.
      • Still nothing arrives: check that the Clickmax URL is registered in the Pagar.me webhook and that the events from step 8 are selected.
      • Invoices and charges arrive without a product, or chargebacks don't show up: the integration's secret key was revoked. Generate another one under Configurações > Chaves de API in Pagar.me, edit the integration in Clickmax and paste the new key.
      • An order refund doesn't show up: check that the order.canceled event is selected in the webhook.
      • A specific event doesn't arrive: events without the customer's email are discarded (Clickmax can't resolve the contact).
      • The automation for a payment-link order stopped firing: the item was probably renamed in Pagar.me. Reopen the trigger, select the product again and save.