Publishing to production

This guide covers the complete process to migrate your integration from sandbox to production — from the technical checklist to the homologation flow and activation.

Overview

Publishing to production involves three parts:

1. Technical checklist — validate that your integration is complete and resilient in sandbox.
2. Homologation — validation by the Appmax team that your integration is working correctly.
3. Production activation — app publication and issuance of production credentials.

INFO

The homologation process is currently conducted via email by the Appmax team. This guide shows how to prepare your integration so that homologation is fast and without rework.

Only public apps go through homologation

Private apps don't require homologation — they're published directly after the technical checklist. The homologation flow described on this page applies only to public apps.

Prerequisites

Before requesting publication to production, confirm your sandbox integration meets every item below.

Installation flow

• [ ] The complete 4-step flow (/oauth2/token → /app/authorize → redirect → /app/client/generate) is implemented and working in sandbox.
• [ ] Your validation URL (health check) is publicly reachable, returns HTTP 200 and an external_id in valid UUID format.
• [ ] Your validation URL responds in under 5 seconds (Appmax timeout).
• [ ] You store the external_id of each installation in your database.
• [ ] You store merchant credentials (client_id and client_secret) securely per installation.

Webhooks

• [ ] Your webhook URL is publicly reachable and returns HTTP 200 for all expected events.
• [ ] You process webhooks idempotently (redeliveries are possible).
• [ ] You respond to the webhook in under 5 seconds — heavy processing must be async.
• [ ] You handle the events relevant to your use case (payment, refund, cancellation, etc.).

API operations

• [ ] You correctly differentiate app credentials (installation) and merchant credentials (transactions on /v1/*).
• [ ] You handle token expiration (1 hour) by requesting a new one when needed.
• [ ] You respect the rate limit (burst 50/s, sustained 5/s).
• [ ] You handle key HTTP status codes (401, 422, 429, 5xx) with proper retry and backoff.
• [ ] Monetary values are always sent as integers in cents (never float).

Security

• [ ] URLs (host, validation, webhook) are using HTTPS with a valid certificate.
• [ ] Credentials (client_secret) are not versioned in code.
• [ ] Logs do not expose credentials, tokens, or sensitive customer data (CPF, card).

Sandbox testing

• [ ] Full installation tested end-to-end in sandbox.
• [ ] At least one order created and paid in sandbox (use the test cards).
• [ ] Webhooks received and processed in sandbox for the main events.
• [ ] Error scenarios tested (declined card, invalid hash, expired token).

Requesting publication

With every item above validated, email [email protected] requesting homologation and publication of your app. Including the information below speeds up the process.

Information to include in the email

Subject: Request for production publication - [App name]

Hi Appmax team,

We have completed sandbox testing and would like to publish our application to production.

**Application info**
- App name: [...]
- App UUID: [...]
- App Numerical ID: [...]
- Type: [public / private]
- Category: [...]

**Production URLs**
- Host: https://[...]
- Validation URL (health check): https://[...]
- Webhook URL: https://[...]
- Callback URL (url_callback): https://[...]

**Technical checklist**
- [x] Installation flow complete and tested in sandbox
- [x] Validation URL responding HTTP 200 with external_id (UUID) in < 5s
- [x] Webhook URL responding HTTP 200 in < 5s
- [x] Integration idempotent and resilient to retries
- [x] Payment, webhook, and error tests completed in sandbox

**Use case**
[Briefly describe what the app does and who the merchants using it are.]

TIP

The more information you provide upfront, the faster the turnaround. Avoid incremental submissions like "I'll send URLs later" — the team needs everything to start homologating.

Homologation

The Appmax team will:

1. Review the submitted information and your app's behavior in sandbox.
2. Test the installation flow and transactions manually.
3. Validate that the validation URL, webhooks, and credentials are operating correctly.
4. Publish the app once everything is approved.

During homologation, the team may request adjustments (e.g., improve error handling, adjust timeout). Keep the sandbox environment available until final approval.

Test scenarios evaluated

The list below summarizes the essential scenarios evaluated during homologation. Testing them in sandbox beforehand speeds up the process — other tests may be performed, but checking these first improves accuracy.

General validations

• [ ] App logo
• [ ] App description
• [ ] Support email
• [ ] App installation

Purchase and refund — test with both an individual (CPF) and a business (CNPJ) customer

Scenario	Card with interest	Card without interest	Pix	Boleto
Purchase	☐	☐	☐	☐
Full refund	☐	☐	☐	☐
Partial refund	☐	☐	☐	☐

Other scenarios

• [ ] Soft descriptor on card purchases
• [ ] Tracking code integration
• [ ] IP recorded on orders
• [ ] Purchase with discount coupon
• [ ] Purchase with shipping + interest
• [ ] Purchase with shipping + discount coupon
• [ ] Purchase with more than one different product in the cart
• [ ] Purchase with multiple units of the same product
• [ ] Order status updates

INFO

If your app isn't focused on payment processing through Appmax, the scenarios above may be disregarded — the review follows other criteria.

What changes in production

Item	Sandbox	Production
Authentication	https://auth.sandboxappmax.com.br	https://auth.appmax.com.br
API	https://api.sandboxappmax.com.br	https://api.appmax.com.br
Authorization redirect	https://breakingcode.sandboxappmax.com.br/appstore/integration/HASH	https://admin.appmax.com.br/appstore/integration/HASH
Credentials	Received at the start of testing	Issued after homologation
Cards accepted	Only test cards	Real cards
Pix/boleto	Simulated	Real, with effective charge
Webhooks	Sent to the sandbox URL	Sent to the production URL

WARNING

Update every URL of your integration when migrating to production — not just the API one. Authentication, redirect, and panel-configured URLs (host, validation, webhook) also change.

After publication

After your app is published, we recommend:

• [ ] Setting up monitoring on validation and webhook URLs (uptime, latency, errors).
• [ ] Setting up alerts for health check failures and 5xx spikes.
• [ ] Tracking the webhook delivery rate in the first days.
• [ ] Keeping credentials in a secret manager (AWS Secrets Manager, Vault, etc.), not plain environment variables.
• [ ] Preparing a runbook for credential rotation in case of leaks.

Troubleshooting

"I sent the homologation email and got no reply"

Check:

1. That the email was sent to [email protected].
2. That it did not land in your inbox's spam.
3. That you included all checklist information (apps with incomplete data stay in queue).

If there's still no reply, follow up on the original email thread (do not open a new thread) and include a summary of what has already been validated. For general questions during integration (outside the homologation process itself), use [email protected].

"I'm getting 401 in production with credentials that worked in sandbox"

Sandbox credentials do not work in production. After homologation, you'll receive new credentials specific to production. Replace in every key in your system:

• App client_id and client_secret
• Merchant client_id and client_secret (will be regenerated on the first production installation)

"My app was published, but the first real installation failed"

Most common behaviors:

• The production validation URL is not publicly reachable.
• The production webhook URL returns error for real events (issue that didn't appear in sandbox due to lower volume).

Check logs, firewall, and IP rules. See Installation troubleshooting for details.

"I can no longer access the old credentials"

Production credentials are issued once after homologation. Store securely. If you lose them:

1. Use the Appmax panel to request regeneration (may invalidate active integrations).
2. Contact [email protected] for guidance.

Next steps

• Monitor rate limit — set up alerts before hitting limits.
• Understand order statuses — to correlate events in production.
• Review webhooks — ensure every relevant event is being consumed.