English

Português

English

Português

Appearance

Create an application ​

This guide covers the application creation in the Appmax panel: the public vs private decision, what you need before you start, and the three form steps.

For the reference of the identifiers and URLs the app exposes after creation (App UUID, App Numerical ID, Host, validation URL, webhook URL), see App identifiers and URLs.

Public or private? ​

The first decision is the application type. It cannot be changed later — choose based on the audience that will use it.

AspectPublicPrivate
VisibilityListed in the Appstore for any merchantVisible only to merchants you invite
Ideal forPlatforms, ERPs, integrators serving multiple merchantsInternal integration or single client
MerchantsUnlimited — any merchant can installOnly merchants authorized by you
ReviewRequired by the Appmax team before publishingNot required

When to use public?

If you're building a platform that will be used by multiple merchants (e.g., ERP, gateway, e-commerce), choose public. This allows any merchant in the Appstore to install your app without an invitation.

Requirements ​

Business ​

  • Active CNPJ — required to create a developer account on the Appstore.

Technical ​

Before submitting the form, you need two public URLs on your system:

URLWhen it's calledReference
Validation URLAppmax makes a server-to-server POST during the last step of installation (/app/client/generate). Your URL must respond HTTP 200 with { "external_id": "<UUID>" }.Installation flow — health check
Webhook URLAppmax sends events (order created, paid, refunded, etc.) during merchant operation.Webhooks

Test the validation URL before creating the app

The whole installation aborts with 500 if the validation URL doesn't answer correctly. Use the interactive tool to verify the contract (HTTP 200 + unique external_id UUID per call) before submitting the form.

Creation steps ​

The form in the panel has three steps.

1. About the application ​

Provide the basic details:

  • Application name — the name displayed to merchants (up to 30 characters).
  • Support email — address for users to reach out. It's also where Appmax sends communications about review status — use a monitored mailbox.
  • Application description — purpose, benefits, and services offered (up to 100 characters).
  • Billing model — choose between:
    • Billing via external platform — billing is handled on your own platform, with no Appmax involvement.
    • Billing via Appmax — a fixed monthly amount charged to the merchant, deducted from the partner balance.

2. Application images ​

Upload the image that will serve as the application avatar.

Required image specification

  • Square format of 1200px x 1200px
  • PNG or JPG
  • No rounded corners

3. Application settings ​

Choose the webhook events your application will receive. The Appstore exposes 29 events across 4 categories:

  • Order — creation, payment, refund, chargeback, and variations (Pix, boleto, upsell).
  • Customer — creation, contact, and interest.
  • Payment — late authorization and non-authorization.
  • Subscription — creation, cancellation, recurring charge.

Select only the events your integration actually processes — subscribing to events you ignore increases load without benefit and complicates auditing. The full list, payloads, and per-event examples are in Webhooks.

TIP

You can change the event selection at any time from the panel, without having to recreate the application.

After submission ​

When you complete the three steps, a modal opens with two options:

  • Submit for review — sends the application for review by the Appmax team. Required for public apps.
  • Test — the team contacts you to provide access to the staging environment.

Click "View Application" and then "Develop" to see the identifiers and URLs generated — those values are the foundation for implementing the installation flow. See App identifiers and URLs for the full per-field reference.

Next steps ​